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

Fix:

1. Validate:

chowbea-axios validate --strict

2. Force regeneration:

chowbea-axios fetch --force

3. 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.

Error Messages Reference

Config Errors

Network Errors

Spec Errors

Generation Errors

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."