Codestin Search App

Read a runtime stack trace and ask the module graph which definitions its frames name. trace-error classifies reported frames as in-project, inside an installed dependency, or outside the analyzed corpus, then resolves the in-project ones against the definitions fallow already extracted.

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

The trace comes from a file argument, from -, or from stdin when no argument is given. A relative path is resolved against the project root, matching --diff-file. V8 and Node traces are supported, as are SpiderMonkey and JavaScriptCore traces.

trace-error is a standalone, best-effort surface. It is not folded into the ranked review brief and is never an input to the focus map or its ranking.

What it refuses to do

The command reports what it could not answer instead of guessing.

A frame matching several definitions reports ambiguous. It lists bounded candidates and records additional matches in candidates_omitted.
A frame matching nothing reports not_found rather than disappearing from the output.
A frame the graph was never asked about reports not_attempted, with the reason.
Reported frames stay in frames[] in input order. counts publishes their per-outcome totals, while frames_omitted records frames beyond the report limit.

Exact project-relative or absolute file paths take priority over abbreviated suffix matches. If an abbreviated path matches multiple modules, the result preserves that ambiguity. No source maps are read. A frame inside generated build output is reported as such, because a stale map rebinds silently to the wrong line 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. Input is limited to 1 MiB. The report includes up to 256 frames and up to 10 candidate definitions per frame; omitted counts remain explicit. Oversized input exits with code 2.

Human output

$ fallow trace-error crash.txt

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 prints its origin and resolution as a [origin/resolution] pair, with the reason on the indented line below.

JSON output

$ fallow trace-error crash.txt --format json

{
  "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, verbatim and unparsed. Omitted when the input began 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 frame’s file sits 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 withheld from the array by a cap. `0` when nothing was withheld.
`frames[].line_mismatch`	boolean	Set on a `resolved` frame whose line sits far from the declaration it matched, so the runtime may have run a same-named definition elsewhere. 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 withheld from the array by a cap.

counts.frames is the number of reported frames. Both resolved + ambiguous + not_found + not_attempted and in_project + node_modules + out_of_corpus equal that number. Add counts.frames_omitted to recover the total number of recognized input frames. A trace that is entirely unrecognised reports zero frames and a non-zero unparsed_lines, rather than looking like an empty trace.

For agents

The trace_error MCP tool wraps this command. Feed it the stack trace from a failing test or a production error, then read frames[].candidates[] for the files worth opening. A not_found result on an in-project frame means the graph could not match its name. The function may be module-local, or the runtime name may differ from the extracted definition.

fallow trace

Walk a symbol’s call chain, or find the shortest import path between two modules.

Inspect a target

Compose one evidence bundle for a file or exported symbol.

MCP integration

Use fallow tools from AI coding agents.

Commands

fallow trace-error

What it refuses to do

Options

Human output

JSON output

Key fields

For agents

See also

fallow trace

Inspect a target

MCP integration

​What it refuses to do

​Options

​Human output

​JSON output

​Key fields

​For agents

​See also

fallow trace

Inspect a target

MCP integration

What it refuses to do

Options

Human output

JSON output

Key fields

For agents

See also