Troubleshooting

Database File Not Found

Run the command from the app that produced the DevTools file, or pass its absolute path:

aisdk-dt runs --file /absolute/path/to/.devtools/generations.json

Confirm AI SDK DevTools is enabled and that the app has completed at least one generation.

No Runs Found

The file can be valid but empty. Trigger one request in the app, then rerun aisdk-dt runs. Add --all if you specifically need child runs.

Partial or Corrupt JSON

The CLI retries a likely active-write race for a short bounded window when the file changes. If invalid JSON remains unchanged, it reports the final parse error. Wait for the app write to finish and retry. If it still fails, preserve the file and validate it with a local JSON tool before replacing anything.

File Exceeds the Safety Limit

The default database limit is 100 MiB. Inspect the file size first. If the size is expected and local disk/memory capacity is adequate, raise the limit deliberately:

aisdk-dt runs --max-file-bytes 209715200 --file <path>

Unknown Content

New AI SDK content parts do not invalidate the whole database. Semantic message output reports them with unsupported: true. Update aisdk-dt first; use a narrow local step --field or raw --json-path query only if the metadata is insufficient.

Invalid Run or Step ID

Refresh IDs from the same database:

aisdk-dt runs --limit 10 --file <path>
aisdk-dt steps <runId> --file <path>

Do not reuse IDs copied from a different checkout or regenerated file.

Local Package Is Not Resolved

If aisdk-dt is a project dependency, use the project package manager:

pnpm exec aisdk-dt --version

From this repository, build the workspace binary before using it from the example:

pnpm --filter aisdk-dt run build

Node.js Version Mismatch

The CLI requires Node.js 20+. The repository workspace requires Node.js 22.18+, 24.11+, or 26+, and the example requires Node.js 22+. Check node --version and switch runtimes before reinstalling dependencies.