Troubleshooting

This guide covers common issues you might encounter and how to resolve them.

Common Issues

Types Seem Stale

Symptom: Your generated types don't match the current API.

Solution: Delete the cache and regenerate:

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

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

Missing operationId Warning

Symptom: You see warnings like "Skipping operation without operationId".

Solution: This means some endpoints in your OpenAPI spec don't have operationId defined. While the path-based API will still work, operation-based methods won't be generated for these endpoints.

Run the validate command to see all issues:

chowbea-axios validate

Ask your API team to add operationId to all operations in the spec.

Network Errors During Fetch

Symptom: Fetch fails with network errors.

Possible causes:

1. API server is not running
2. Incorrect endpoint URL
3. Authentication required

Solution:

1. Check your API server is running:

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

2. Verify the endpoint in your config:

chowbea-axios status

3. If authentication is required, add HTTP Basic Auth (the supported scheme today):

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

See Authentication → Protected OpenAPI Specs for details.

Scripts Missing from package.json

Symptom: The api:* scripts aren't in your package.json.

Solution: Re-run init to add them:

chowbea-axios init

Or add them manually:

{
  "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"
  }
}

Basic Auth Not Working

Symptom: Fetch fails with 401/403 even though [fetch.auth] is configured.

Solution: Check environment variable interpolation:

1. Ensure the env vars are set:

echo $SWAGGER_USER
echo $SWAGGER_PASS

2. Verify your config syntax — $VAR and ${VAR} both work:

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

3. Export the variables before running:

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

If the vars aren't set, the CLI prompts for them interactively in a TTY and fails fast in CI.

Dashboard Won't Open / Falls Back to Headless

Symptom: Running chowbea-axios with no command prints a hint about falling back to headless mode.

Solution: The dashboard requires Bun. Install Bun, or use the headless CLI commands (fetch, generate, etc.). The headless surface is fully supported under Node alone — Bun is only needed for the interactive TUI.

Generation Errors

Symptom: Generation fails or produces TypeScript errors in _generated/.

Solution: Validate your spec first — the built-in generator surfaces problems by category:

chowbea-axios validate --strict

TypeScript Errors in Generated Files

Symptom: TypeScript compiler errors in _generated/ files.

Possible causes:

1. OpenAPI spec has invalid schemas
2. Circular references in spec
3. Incompatible TypeScript version

Solution:

1. Validate the spec:

chowbea-axios validate --strict

2. Regenerate with force:

chowbea-axios fetch --force

3. Check TypeScript version (5.x recommended)

Error Messages Reference

Config Errors

Network Errors

Spec Errors

Generation Errors

Getting Help

If you're still stuck:

1. Run with verbose output:

chowbea-axios fetch --verbose

2. Check the status of your setup:

chowbea-axios status

3. Validate your OpenAPI spec:

chowbea-axios validate --strict

4. Open an issue on GitHub with:
   • The error message
   • Your api.config.toml (remove sensitive headers)
   • Your OpenAPI spec (or a minimal reproduction)