---
name: troubleshooting
description: "Invoke when debugging failures, diagnosing unexpected behavior, or investigating test failures. Contains project-specific failure modes, diagnostic workflows, and known issues."
---

# Troubleshooting

## Detected

### Common Issues
- **TypeScript reports "possibly null" or "possibly undefined" after a type guard, but only in async functions — the guard works in sync code** — Type narrowing does not persist across `await` boundaries because the variable could be reassigned between suspension points. Re-narrow after each `await`: `if (!x) throw` before the `await`, then `if (!x) throw` again after.
- **Object literal type is widened to `string` instead of the literal value, or array type is `string[]` instead of a tuple** — Add `as const` to the declaration: `const x = { type: "success" } as const` gives `{ readonly type: "success" }` instead of `{ type: string }`. For arrays: `const arr = ["a", "b"] as const` gives `readonly ["a", "b"]` instead of `string[]`.
- **"ERR_REQUIRE_ESM" when importing an ESM-only package, or "SyntaxError: Cannot use import statement in a module"** — ESM-only packages (like `chalk` v5+, `execa` v6+, `node-fetch` v3+) cannot be `require()`'d. Either: (1) switch your project to ESM (`"type": "module"` in package.json), (2) use dynamic `import()` for the ESM package, or (3) pin an older CJS-compatible version.
- **Process crashes with "UnhandledPromiseRejection" — an async function throws but nothing catches it** — Ensure every Promise chain has a `.catch()` or is inside a `try/catch` in an `async` function. For fire-and-forget promises, add `.catch(err => logger.error(err))`. Check for missing `await` on async calls — without it, the rejection is unhandled. Prevention: Add `process.on("unhandledRejection", handler)` as a safety net, but fix the root cause — unhandled rejections indicate a code bug.
- **Tests hang indefinitely in CI or when run from scripts — process never exits** — Vitest defaults to watch mode in interactive terminals. Pass `--run` flag to run tests once and exit: `vitest run` instead of `vitest`. In CI, Vitest auto-detects non-interactive environments, but scripts piping output may still trigger watch mode. Prevention: Always use `vitest run` in CI scripts and non-interactive contexts.
- **Tests pass individually but fail when run together — mock from one test bleeds into another** — Call `vi.restoreAllMocks()` in `afterEach` or set `mockReset: true` / `restoreAllMocks: true` in `vitest.config.ts`. Module mocks (`vi.mock()`) persist across tests in the same file — use `vi.unmock()` or restructure to avoid shared module-level mocks.

## Rules

**Pre-commit hook rejects commit.** The hook runs `tsc --noEmit` (source + tests) and `eslint`. It does NOT run tests. The most common cause is a type error. Run `cd packages/cli && pnpm typecheck` to see the specific error. Don't use `--no-verify` to skip the hook — the build (tsup/SWC) strips types without checking, so the hook is the only enforcement.

**Gotcha triggers don't fire on the expected stack.** Gotcha triggers match against `stack.*` fields which store DISPLAY NAMES, not package names. `{ aiSdk: 'Anthropic' }` fires. `{ aiSdk: '@anthropic-ai/sdk' }` does not. Check `packages/cli/src/data/gotchas.ts` for existing trigger values.

**Schema detection shows wrong file or wrong model count.** In monorepos, census first checks `{root}/prisma/schema.prisma` and `{root}/schema.prisma` for each workspace package. If multiple schema files exist, the scan picks the one with the most models. For multi-file schemas (Prisma `prismaSchemaFolder`), models are counted across all `.prisma` files in the directory. If the wrong schema is selected, check which workspace packages have a `prisma/` directory.

**Re-init doesn't show new template content.** CLAUDE.md, AGENTS.md, and agent definitions use merge-not-overwrite — existing files are preserved. To see fresh template output after changing templates, delete the existing files first: `rm CLAUDE.md AGENTS.md && rm -rf .claude/agents/` then re-run `ana init --force`.

**`pnpm test` at workspace root behaves differently than in packages/cli.** The root `test` script runs through turbo, which handles argument passthrough differently. Use `cd packages/cli && pnpm test -- --run` for reliable test execution with the `--run` flag. Running `pnpm test --run` from the workspace root may fail or pass arguments incorrectly.

## Gotchas
*Add new entries as they're discovered during development. Each entry should describe the symptom, the cause, and the fix.*

## Examples
*Not yet captured. Add diagnostic workflows showing how to investigate common failures.*