Explain Error

Diagnose the error in $ARGUMENTS against this codebase and propose a specific fix. Your job is to explain why it happens and how to fix it — not to restate the message back. Do not change any files; report your findings and the recommended fix.

Scope

$ARGUMENTS is the raw error to diagnose — an exception message, a stack trace, a compiler/type error, or a chunk of failing log output. Parse it for the signal that matters:

The error type/class and message (TypeError, NullPointerException, ECONNREFUSED, error[E0382], ...).
The top in-repo frame — the first stack frame pointing at a file in this project, not in node_modules, the standard library, or a vendored dependency. That frame is usually where the fix lives.
Any identifiers in the message: variable names, function names, file paths, line numbers, error codes.

If $ARGUMENTS is empty, do not guess. Ask the user to paste the full error or stack trace, or point you at the failing command (e.g. npm test, cargo build) so you can reproduce it and capture the output yourself.

Step 1 — Locate the originating code

Find the exact line the error blames, then read enough around it to understand the context.

# Jump to the file:line from the top in-repo stack frame
# e.g. "at src/lib/auth.ts:42" -> open that file around line 42

When the trace is minified, transpiled, or points at a build artifact, search for the symbols in the message instead:

# Find where the named function / variable / message string is defined
rg -n "functionFromTheTrace|the exact error string" src

NOTE

Trust the first in-repo frame, not the last frame. The deepest frame is often inside a library doing exactly what it was told — the bug is usually at the boundary where your code called it with bad input.

Step 2 — Identify the likely root cause

Explain in plain terms what actually went wrong, one level beneath the message. Map the error to its underlying condition rather than echoing the text:

The message says	The real cause is usually
`Cannot read properties of undefined`	a value was never assigned, an async result wasn't awaited, or a lookup missed
`NullPointerException` / `nil` deref	an unchecked optional or a failed-but-ignored return
`ECONNREFUSED` / `connection refused`	wrong host/port, service not running, or env var unset
`Module not found`	missing dependency, bad import path, or stale build cache
type / borrow / lint error	a contract the compiler is enforcing — read it literally

State the cause as a single clear sentence: "session is undefined here because getSession() returns a Promise that the caller never awaits, so the .user access runs before it resolves."

Step 3 — Confirm before you commit to an answer

When practical, verify the hypothesis instead of asserting it. Use read-only checks only.

# Re-run the failing command to confirm the error and see the full trace
npm test 2>&1 | tail -40
 
# Inspect runtime conditions the trace implies (env, service, versions)
# prints key names only — omit `cut -d= -f1` if you need the values
printenv | cut -d= -f1 | rg -i 'DATABASE|API|PORT'

NOTE

Reproduce or confirm the cause with a read-only command whenever it's cheap to do so — a confirmed diagnosis beats a plausible one.

WARNING

Stay read-only. Do not run migrations, installs, formatters, or anything that mutates the repo, the database, or remote state to "test" a theory. Confirm by reading and by re-running the same failing command, nothing more.

Step 4 — Report the diagnosis and fix

When the cause is clear, report it directly:

## Error: <error type — one-line summary>
 
**Origin:** `path/to/file.ts:42` — <what this line was doing>
 
**Root cause:** <the plain-terms why, one level below the message>
 
**Fix:** <the specific change — code, not vibes>
 
    - const user = getSession().user;
    + const user = (await getSession()).user;
 
**Confidence:** High — reproduced via `npm test`; the trace points squarely here.

When the cause is ambiguous, list the top candidates ranked by likelihood, each with the evidence for it and the one-line check that would confirm or rule it out:

**Most likely (≈70%):** <cause> — confirm with `<read-only check>`
**Possible (≈20%):** <cause> — confirm with `<read-only check>`
**Long shot (≈10%):** <cause> — confirm with `<read-only check>`

End with the single highest-value next step: the fix to apply, or the one check that collapses the remaining ambiguity.

Scope

Step 1 — Locate the originating code

Step 2 — Identify the likely root cause

Step 3 — Confirm before you commit to an answer

Step 4 — Report the diagnosis and fix

Related