Diagnostics
How marmot reports errors to people, to scripts and to coding agents.
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. |
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
The parts, top to bottom:
- The severity and code, then the message.
-->and the position of the primary span.- 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
.... = note:lines with what the compiler knows, such as the method a type lacks.help:with a suggested fix shown as a diff.(check it)marks fixes that are likely but not certain.- A summary and the
marmot explaincommand for the code.
Plain
The same error off a terminal, for scripts and editors that parse go build output:
./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 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 for the schema, and Error codes for every code.
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=jsonit writes one object:
{"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.