# Diagnostics (/docs/diagnostics)

Every error has a stable code (`M0002`) that `marmot explain` describes. The same diagnostic is
written in one of three modes:

| Mode | When | What it looks like |
| --- | --- | --- |
| human | stderr is a terminal | `error[CODE]: message`, then `--> file:line:col`, the source with carets under the exact span and a label saying what is wrong there, labels on related spans, `= note:` and `= help:` lines, and fixes as `help:` with a diff. At most 10 errors, sorted by file and line, then a summary. |
| plain | stderr is not a terminal | `file:line:col: message` lines, as the go tool prints them. Tools and tests parse this form; it does not change. |
| json | `-json`, `MARMOT_OUTPUT=json`, or a coding agent environment | JSON Lines on stderr. See [JSON output](/docs/diagnostics/json). |

`MARMOT_OUTPUT=human`, `plain` or `json` overrides the choice. `-color=auto|always|never` sets
color in human mode; `auto` respects `NO_COLOR` and `TERM=dumb`.

## Human [#human]

<Shot name="error-interface" alt="An M0014 error: the primary span under Square{2}, labels on the Shape interface and on the Area method with a pointer receiver, a note, and a fix as a diff" />

The parts, top to bottom:

1. The severity and code, then the message.
2. `-->` and the position of the primary span.
3. The source lines involved, with carets under the primary span and dashes under related
   spans, each with a label. Lines in between are folded as `...`.
4. `= note:` lines with what the compiler knows, such as the method a type lacks.
5. `help:` with a suggested fix shown as a diff. `(check it)` marks fixes that are likely but
   not certain.
6. A summary and the `marmot explain` command for the code.

## Plain [#plain]

The same error off a terminal, for scripts and editors that parse `go build` output:

```text
./main.go:12:16: cannot use Square{…} (value of struct type Square) as Shape value in variable declaration: Square does not implement Shape (method Area has pointer receiver)
```

## JSON for coding agents [#json-for-coding-agents]

JSON is the default when one of these variables is set (to anything but `0`) and
`MARMOT_OUTPUT` is not: `CLAUDECODE`, `AI_AGENT`, `CODEX_SANDBOX`, `GEMINI_CLI`,
`CURSOR_AGENT`, `OPENCODE`, `GOOSE_TERMINAL`. Each diagnostic carries its spans, the enclosing
function, the source lines around it, the fixes as edits, and `rendered`, the exact human form.
An agent can apply a fix without opening the file. `marmot mcp` serves the same data over the
Model Context Protocol.

See [JSON output](/docs/diagnostics/json) for the schema, and [Error codes](/docs/diagnostics/codes)
for every code.

## Runtime errors [#runtime-errors]

A program built by marmot reports a panic or fatal error in the same three modes, chosen when
it happens.

- On a terminal the report lists the program's frames with their source lines and folds
  library frames.
- Off a terminal the trace is the plain Go form.
- With `MARMOT_OUTPUT=json` it writes one object:

```json
{"schema":1, "kind":"panic", "code":"M0020", "message", "valueType", "chain", "goroutine",
 "frames":[{"func", "file", "line", "col", "inlined", "user"}],
 "goroutines":{"total", "running", "runnable", "waiting"}, "exitCode":2}
```

`kind` is `fatal` and the code `M0021` for fatal errors. `marmot run` in JSON mode passes
`MARMOT_OUTPUT=json` to the program.