HAP robot debugging code with magnifying glass

HAP's Learning Lab

Reading Errors

This is my cheat sheet for reading errors. When I started out, every red line in the terminal felt like a personal attack. Now I know that the error message is trying to help me — I just had to learn how to listen. Prof. Teeters taught me a system, and it changed everything.

Most of what I know about reading errors came from Station 6, where I learned to be the human architect who triages before asking for help. 🟠

Date-stamped: March 2026. Error formats change as tools update. The triage method stays the same: read the first line, identify the category, gather context, then ask for help.

Signal vs Noise

The first error is usually the cause. Everything after is often consequence. I learned from Prof. Teeters to read the first red line before panicking.

The rule: When you see a wall of red text, do not scroll to the bottom. Scroll to the top. The first error triggered everything else. Fix that one, and half the others may disappear on their own.

Vite and Build Errors

Build tools like Vite produce cascading errors. The real problem is at the top — the rest is noise.

1

The Pattern

Lines 1-3 are the real error. Lines 4-20 are cascade. When I was practicing, I used to copy all 200 lines to my agent. Prof. Teeters stopped me and said: "Give it the first three lines. That is where the answer lives."

# What the terminal shows:
error: Could not resolve "./components/Headr.astro"
  at src/pages/index.astro:3:25
  ... 17 more lines of stack trace you can ignore
2

What to Copy

Copy the first 3 lines to your agent, not all 200. The file name and line number are the signal. The stack trace is noise — unless your agent specifically asks for it.

Browser Console Errors

The browser console groups errors into categories. Identify the category first, then ask the right questions.

SyntaxError

Something is written wrong — a missing bracket, a typo, an extra comma. The browser cannot even parse the file.

Uncaught SyntaxError: Unexpected token '}'
  at script.js:42

ReferenceError

You used a name that does not exist. Usually a typo or a missing import.

Uncaught ReferenceError: contaner is not defined
  at script.js:15

Network Error

A fetch or resource load failed. Check the URL, check if the server is running, check your internet connection.

GET http://localhost:4321/api/data 404 (Not Found)

CORS Error

The browser blocked a cross-origin request. This is a server configuration issue, not a code bug.

Access to fetch at 'https://api.example.com'
from origin 'http://localhost:4321'
has been blocked by CORS policy

Three questions to ask yourself: What file? What line? What did I expect vs what happened? If you can answer those three, you have enough context to ask your agent for help.

Terminal Errors

Terminal errors are usually short and direct. The message tells you exactly what went wrong — once you know the vocabulary.

?

command not found

The tool is not installed, or it is not in your PATH. This was tricky for me too — I kept thinking I had broken something, but it just meant I needed to install the tool first.

zsh: command not found: netlify
# Fix: npm install -g netlify-cli
!

permission denied

You do not have the right permissions to run this command or access this file. Do not just add sudo without understanding why.

bash: ./script.sh: Permission denied
# Check permissions first:
ls -la script.sh
/

No such file or directory

Wrong path. Always run pwd first to confirm where you are. I learned from Prof. Teeters: most "file not found" errors are really "I am in the wrong directory" errors.

cat: src/index.html: No such file or directory
# First check:
pwd
ls src/

What to Give the Agent

When I ask my AI agent for help with an error, I give it these five things. Prof. Teeters called this "context engineering for debugging."

1

Your OS and shell

"I am on macOS using zsh" or "I am on Windows using Git Bash." This changes what commands and paths look like.

2

The exact command you ran

Copy-paste it. Do not paraphrase. "I ran npm something" is not helpful. npm run build is.

3

The exact error (first 3-5 lines)

Copy the first 3-5 lines of the error output. Not the whole thing — the signal, not the noise.

4

What you expected to happen

"I expected the dev server to start" or "I expected the file to be created in src/." This helps the agent understand the gap between expectation and reality.

5

What you already know about the project

"This is an Astro project" or "I just ran npm install." Context about the project helps the agent narrow down the problem fast.

What NOT to Do

I made all of these mistakes. More than once. 🟠

Do not paste 200 lines of output

Your agent will drown in noise. The first 3-5 lines contain the answer. The rest is cascade. I used to dump everything and wonder why the agent gave confused responses.

Do not say "it doesn't work"

That tells the agent nothing. What command did you run? What happened? What did you expect? "It doesn't work" is the least helpful thing you can type.

Do not skip context

Your agent cannot see your screen. It does not know your OS, your shell, your project structure, or what you just tried. The five items above are the minimum. Without them, the agent is guessing.

← Back to Learning Lab Hub

HAP waving goodbye