Solutions for common errors and problems with go-minitrace
This page collects solutions for common errors and unexpected behavior when using go-minitrace.
What happened: The Codex converter encountered a session file with a JSONL format it does not recognize.
Cause: Older Codex sessions or sessions from a different Codex version may use a format the adapter has not been taught to parse.
Solution: The converter skips sessions that fail to convert and keeps going. Each failed session is reported as a diagnostics row with status: failed and an error column describing what went wrong; successfully converted sessions are written normally. The command exits with an error only if every discovered session failed to convert. To find the problematic sessions, filter the output rows:
go-minitrace convert codex --source-dir ~/.codex --output-dir ./output --output json | jq '.[] | select(.status == "failed")'
What happened: The convert command ran without errors but produced no minitrace files.
Cause: The source directory does not contain files matching the expected patterns, or the directory path is wrong.
Solution: Run discover first to confirm sessions exist:
go-minitrace discover claude-code --output json | jq length
If discover reports 0 sessions, check the --source-dir path.
What happened: The converter cannot read session files.
Cause: Session files are owned by a different user or have restrictive permissions.
Solution: Check file ownership with ls -la on the source directory. If needed, adjust permissions or run as the appropriate user.
What happened: Converting Claude Code produced many more files than expected.
Cause: Claude Code subagent sessions each become their own minitrace file. A session that delegates to 10 subagents produces 11 files (1 main + 10 subagent).
Solution: This is expected behavior. Filter subagent sessions in queries:
WHERE source_format NOT LIKE '%subagent%'
What happened: A query against sqlite_master (or any other object outside the allowlist) was rejected with:
query references disallowed table/view "sqlite_master"; use db.schema() or db.tables() from JS to introspect the schema
Cause: All SQL runs through a sandboxed read-only runner that only allows the normalized tables (sessions, turns, tool_calls, turn_tool_calls, files, annotations, handovers, metrics, attachments, events) plus the sessions_base compatibility view. Introspection tables are blocked.
Solution: Use db.schema() or db.tables() from a JS handler, or go-minitrace help minitrace-schema for the column reference.
What happened: Saved SQL written for the removed DuckDB engine fails with missing functions (UNNEST, LEFT, json_extract_string) or unknown columns.
Cause: The DuckDB backend was removed. Queries now run on normalized SQLite: what used to be JSON arrays inside sessions_base are real child tables.
Solution: Rewrite against the normalized tables. UNNEST(tool_calls) becomes FROM tool_calls, LEFT(x, n) becomes substr(x, 1, n), CAST(x AS DATE) becomes date(x). See go-minitrace help query-duckdb for the full migration table. Session-level ->> SQL still works against the sessions_base compatibility view.
What happened: Running a SQL query command printed:
Warning: --db-path, --table-name, and --persist-loaded are deprecated; SQL query commands now run against the normalized SQLite database built from --archive-glob.
Cause: These flags configured the removed DuckDB backend. SQL commands ignore them; JS commands still see the values on mt.runtime for backwards compatibility, but they no longer affect where queries run.
Solution: Drop the flags. Point --archive-glob at your archives; the normalized database is built (and cached) automatically. In SQL command files, {{TABLE_NAME}} now renders as the sessions_base compatibility view.
What happened: You want to query the shell command from bash tool calls.
Cause: In the old engine this required guessing adapter-specific JSON paths. The normalized schema promotes it to a real column.
Solution: Use the command column directly:
SELECT session_id, tool_name, command
FROM tool_calls
WHERE command LIKE '%docmgr%';
Raw adapter-specific argument payloads remain available in arguments_json and raw_json when you need them:
SELECT json_extract(arguments_json, '$.command') AS raw_cmd
FROM tool_calls
WHERE tool_name = 'bash'
LIMIT 5;
What happened: A query ran successfully but returned no results.
Cause: The --archive-glob pattern does not match any files, or the WHERE clause filters everything out.
Solution: First check what loaded:
go-minitrace query run \
--archive-glob './output/active/*/*.minitrace.json' \
--sql 'SELECT COUNT(*) AS sessions FROM sessions'
If this returns 0, check the glob path with ls:
ls ./output/active/*/*.minitrace.json | head
What happened: The query command exited with this error.
Cause: No query mode flag was given.
Solution: Add one of the three query mode flags:
go-minitrace query run --archive-glob '...' --preset session-list
What happened: The command rejected the flag combination.
Cause: More than one query mode was specified.
Solution: Use exactly one of --preset, --sql, or --sql-file.
What happened: A JavaScript query command failed and printed a one-line error like:
Error: no sessions matched (file.js:12:3)
and, when run with --output json, a JSON object like:
{"error":"Error: no sessions matched","location":"file.js:12:3","command":"my-command"}
Cause: This is the intended failure shape. JS errors are collapsed to the first error line plus the first stack-frame location instead of a full native stack trace, and --output json emits a parseable {"error": ...} envelope on stdout so JSON consumers never receive empty output.
Solution: Read the error and location fields; fix the script at the reported file/line. Automation consuming --output json should treat the presence of an error key as failure.
What happened: A query over tool_calls or turns produces no output.
Cause: All matched sessions have no tool calls/turns, or your WHERE clause filters out all rows.
Solution: Check that your filter includes sessions that actually have data:
SELECT session_id, tool_call_count AS tools
FROM sessions
WHERE tool_call_count > 0
LIMIT 5;
Then verify the raw distribution without the extra WHERE clause:
SELECT tool_name AS tool, COUNT(*) AS uses
FROM tool_calls
GROUP BY tool
ORDER BY uses DESC;
What happened: validate reports all files as valid JSON, but queries return unexpected results.
Cause: validate currently checks JSON syntax only, not schema compliance. Files can be valid JSON but have wrong or missing fields.
Solution: This is expected. Schema validation is planned for a future release. Check specific files manually if queries return unexpected data:
cat ./output/active/2026-03/abc123.minitrace.json | jq '.metrics'
What happened: Discovery takes a long time to complete.
Cause: The source directory contains thousands of session files and the discovery walks the entire tree.
Solution: This is expected for large session stores. The discovery is read-only and will complete — it just takes time proportional to the number of files.
What happened: Discovery shows format hints you do not recognize.
Cause: The session files may be from a newer or older version of the source tool.
Solution: Check if your go-minitrace version supports the format. Update if needed:
go install github.com/go-go-golems/go-minitrace/cmd/go-minitrace@latest
What happened: Converting thousands of sessions takes a long time.
Cause: Each session file must be read, parsed, and written individually.
Solution: Convert in batches, or convert only the sessions you need with --source-session/--source-list (pi, codex, claude-code) after narrowing candidates with discover ... --cwd-contains ... --since ....
What happened: The first query over a large archive set takes a long time.
Cause: The normalized SQLite database is built from the matching .minitrace.json files on first use.
Solution: The build is cached by archive fingerprint, so subsequent queries against the same globs reuse the cached database and are fast. If the first build times out, raise --timeout-ms, or narrow --archive-glob to the sessions you actually need.
go-minitrace help getting-started — tutorial covering the basic workflowgo-minitrace help convert-commands — conversion flags and per-adapter detailsgo-minitrace help query-commands — query modes and flags