Troubleshooting

Something broke. Probably not the generator's fault — but let's find out before you @channel the backend team.

Common Issues

Types Seem Stale

Symptom: Generated types don't match what the API actually returns. Your IDE lies with confidence.

Fix: Nuke the cache and fetch fresh:

# Delete _internal to reset the spec cache
rm -rf app/services/api/_internal

# Fetch fresh spec and regenerate
chowbea-axios fetch --force

If types look right but app code still references old shapes, check you're importing from api.contracts.ts, not a hand-rolled alias from three sprints ago. See The Query Layer.

Missing operationId Warning

Symptom: "Skipping operation without operationId" during generation.

Meaning: Some endpoints lack operationId in the spec. Path-based api.get("/users") still works. api.op.listUsers won't exist for those endpoints — because there's nothing to name the method after.

chowbea-axios validate

Shows every offender. Ask your API team to add operationId to all operations. This is a spec hygiene issue, not a generator bug.

Network Errors During Fetch

Symptom: Fetch dies with network errors.

Likely causes:

1. API server isn't running
2. Wrong endpoint URL
3. Auth required and not configured

Fix:

1. Confirm the server is up:

curl http://localhost:3000/docs/swagger/json

2. Verify config:

chowbea-axios status

3. If the spec is behind auth, add HTTP Basic (supported scheme today):

[fetch.auth]
type = "basic"
username = "$SWAGGER_USER"
password = "$SWAGGER_PASS"

See Authentication → Protected OpenAPI Specs.

Scripts Missing from package.json

Symptom: No api:* scripts in package.json.

Fix: Re-run init:

chowbea-axios init

Or add them manually — same commands, less hand-holding:

{
  "scripts": {
    "api:fetch": "chowbea-axios fetch",
    "api:generate": "chowbea-axios generate",
    "api:watch": "chowbea-axios watch",
    "api:status": "chowbea-axios status",
    "api:validate": "chowbea-axios validate",
    "api:diff": "chowbea-axios diff"
  }
}

Pair api:watch with your dev server. Your future self will thank you.

Basic Auth Not Working

Symptom: 401/403 despite [fetch.auth] being configured.

Fix: Env var interpolation is almost always the culprit.

1. Confirm vars are set:

echo $SWAGGER_USER
echo $SWAGGER_PASS

2. Config syntax — $VAR and ${VAR} both work:

[fetch.auth]
type = "basic"
username = "$SWAGGER_USER"
password = "${SWAGGER_PASS}"

3. Export before running:

export SWAGGER_USER="..." SWAGGER_PASS="..."
chowbea-axios fetch

Unset vars in a TTY? CLI prompts interactively. In CI? Fails fast. As it should.

Dashboard Won't Open / Falls Back to Headless

Symptom: chowbea-axios with no command prints a headless fallback hint.

Meaning: The interactive dashboard needs Bun. Install Bun, or use headless commands — fetch, generate, watch, etc. Headless works fine under Node alone. Bun is only for the TUI.

See Interactive Dashboard for invocation details.

Generation Errors

Symptom: Generation fails or _generated/ produces TypeScript errors.

Fix: Validate first — the generator surfaces problems by category:

chowbea-axios validate --strict

Fix what validate reports. Regenerate. Repeat until boring.

TypeScript Errors in Generated Files

Symptom: TSC errors pointing at _generated/.

Likely causes:

1. Invalid schemas in the OpenAPI spec
2. Circular references the generator can't flatten
3. TypeScript version mismatch
4. Merge conflicts left unresolved

Fix:

1. Check for conflicts first:

git status
# If you see unmerged paths in _generated/:
chowbea-axios resolve

2. Validate:

chowbea-axios validate --strict

3. Force regeneration:

chowbea-axios fetch --force

4. TypeScript 5.x recommended. If you're on 4.x, upgrade before filing an issue.

Remember: don't edit _generated/ to "fix" errors. Fix the spec. See Generated Files.

Merge Conflicts in Generated Files

Symptom: Git shows conflict markers in _generated/api.operations.ts, _generated/api.types.ts, or other generated files after a merge.

Why it happens: Generated files are thousands of lines long and change frequently. Text-based merging produces unreadable conflicts.

Fix:

# After a merge with conflicts in _generated/
chowbea-axios resolve

The resolve command regenerates the conflicted files from the spec — the only correct resolution for generated code. It stages the result automatically.

See resolve reference for details.

Merge Conflicts in Cache Files (_internal/)

Symptom: Conflicts appear in _internal/.api-cache.json or _internal/openapi.json after a merge.

Why it happens: The cache was accidentally committed. It changes on every fetch (timestamp, hash) and causes meaningless conflicts.

Fix:

# Untrack the cache and add the gitignore rule
chowbea-axios doctor --fix

# Commit the repair
git commit -m "chore: stop tracking _internal cache"

The doctor command detects tracked artifacts and untracks them while keeping the files on disk. Future merges won't touch the cache.

See doctor reference for details.

Error Messages Reference

Config Errors

Network Errors

Spec Errors

Generation Errors

Pinned-Inputs Errors (v3)

Getting Help

Still stuck after the obvious fixes:

1. Verbose output:

chowbea-axios fetch --verbose

2. Setup status:

chowbea-axios status

3. Spec validation:

chowbea-axios validate --strict

4. Open an issue with:
   • The error message (full, not paraphrased)
   • Your api.config.toml (redact secrets)
   • Your OpenAPI spec or a minimal reproduction

The fastest issues to close include reproduction steps. The slowest include "it doesn't work."