fallow trace-error

Go from a runtime stack trace to the definitions in your code that its frames name. Fallow trace-error resolves each frame against the module graph, without reading source maps.

Give fallow trace-error a runtime stack trace, and it tells you which definitions in your project the frames name. First, it sorts each reported frame into one of three origins:

in the project
inside an installed dependency
outside the analyzed corpus

Then it resolves the in-project frames against the definitions that fallow already extracted.

fallow trace-error crash.txt
cat crash.txt | fallow trace-error
fallow trace-error - --format json --quiet

Fallow reads the trace from a file argument, from -, or from stdin when you give no argument. Fallow resolves a relative path against the project root, the same as --diff-file. Fallow supports V8, Node, SpiderMonkey, and JavaScriptCore traces.

trace-error is a standalone, best-effort command. Its results are not part of the ranked review brief, and they never change the focus map or its ranking.

What it refuses to do

When the command cannot answer, it says so, and it does not guess.

A frame that matches several definitions reports ambiguous. It lists a limited number of candidates, and candidates_omitted counts the other matches.
A frame that matches nothing reports not_found. It stays in the output.
A frame that fallow did not try to resolve reports not_attempted, with the reason.
Reported frames stay in frames[] in input order. counts has the total for each outcome. frames_omitted counts the frames beyond the report limit.

An exact project-relative or absolute file path wins over an abbreviated suffix match. If an abbreviated path matches more than one module, the result reports that ambiguity.

Fallow does not read source maps. It reports a frame inside generated build output as generated output. A stale source map can point to the wrong line without a warning, and a wrong line is worse than no line.

Options

trace-error takes the project, output, and performance global flags: --root, --config, --format with human or json, --pretty, --quiet, --no-cache, and --threads.

The input limit is 1 MiB. The report includes up to 256 frames, and up to 10 candidate definitions for each frame. The report always counts what it omits. Input over the limit exits with code 2.

Human output

Stack-trace frames (syntactic; OFF the ranked path)

  source: crash.txt
  error:  TypeError: Cannot read properties of undefined (reading 'title')

  [0] Box components/Box.tsx:12 [in-project/not-found]
        no definition named 'Box' is exported from the module this frame points at; a module-local function is not in the graph's definition set
  [1] renderWithHooks node_modules/react-dom/cjs/react-dom.development.js:14985 [node-modules/not-attempted]
        frame is in an installed dependency, not in project source
  [2] Object.<anonymous> /opt/build/generated/chunk-4f2a.js:1 [out-of-corpus/not-attempted]
        '/opt/build/generated/chunk-4f2a.js' is generated build output; resolving it back to source needs a source map, which this command does not read

  frames 3 | resolved 0 | ambiguous 0 | not found 1 | not attempted 2

Each frame shows its origin and resolution as an [origin/resolution] pair. The indented line below gives the reason.

JSON output

{
  "kind": "trace-error",
  "schema_version": "1",
  "source": "crash.txt",
  "header": "TypeError: boom",
  "frames": [
    {
      "index": 0,
      "raw": "at transformCard (lib/card.transform.ts:22:9)",
      "function": "transformCard",
      "file": "lib/card.transform.ts",
      "line": 22,
      "column": 9,
      "origin": "in_project",
      "resolution": "resolved",
      "candidates": [
        {
          "file": "lib/card.transform.ts",
          "symbol": "transformCard",
          "kind": "export",
          "line": 20
        }
      ],
      "candidates_omitted": 0,
      "reason": "'transformCard' names lib/card.transform.ts:transformCard (export)"
    }
  ],
  "counts": {
    "frames": 1,
    "frames_omitted": 0,
    "in_project": 1,
    "node_modules": 0,
    "out_of_corpus": 0,
    "resolved": 1,
    "ambiguous": 0,
    "not_found": 0,
    "not_attempted": 0,
    "unparsed_lines": 0
  },
  "reason": "1 frame: 1 resolved, 0 ambiguous, 0 not found, 0 not attempted"
}

Key fields

Field	Type	Description
`source`	string	`stdin`, or the path exactly as you wrote it.
`header`	string	The first non-blank line before any frame, as written and not parsed. Omitted when the input starts with a frame.
`frames[].index`	integer	Position in the input trace. Frames keep input order.
`frames[].raw`	string	The frame line as it was read.
`frames[].origin`	`"in_project"` \| `"node_modules"` \| `"out_of_corpus"`	Where the file of the frame is, relative to the analyzed corpus.
`frames[].resolution`	`"resolved"` \| `"ambiguous"` \| `"not_found"` \| `"not_attempted"`	What the graph could say about the frame.
`frames[].candidates[]`	array	Definitions the frame may name, each with `file`, `symbol`, `kind`, and an optional `line` and `member`. Empty unless the resolution is `resolved` or `ambiguous`.
`frames[].candidates_omitted`	integer	Candidates that the cap kept out of the array. `0` when the cap kept nothing out.
`frames[].line_mismatch`	boolean	Set on a `resolved` frame when its line is far from the matched declaration. The runtime may have run a different definition with the same name. Omitted when false.
`frames[].reason`	string	Why this frame has the resolution it has.
`counts.unparsed_lines`	integer	Input lines that did not parse as a frame.
`counts.frames_omitted`	integer	Frames that the cap kept out of the array.

counts.frames is the number of reported frames. resolved + ambiguous + not_found + not_attempted equals that number, and so does in_project + node_modules + out_of_corpus. To get the total number of recognized input frames, add counts.frames_omitted. If fallow recognizes no line in a trace, it reports zero frames and a non-zero unparsed_lines. You can thus tell it apart from an empty trace.

For agents

The trace_error MCP tool runs this command. Give it the stack trace from a failing test or a production error. Then read frames[].candidates[] to find the files to open. A not_found result on an in-project frame means that fallow could not match the frame name to a definition. The function may be module-local, or the runtime name may differ from the extracted definition.