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 headers:

[fetch]
headers = { Authorization = "Bearer $API_TOKEN" }

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

Auth Headers Not Working

Symptom: Fetch fails with 401/403 even though headers are configured.

Solution: Check environment variable interpolation:

1. Ensure the env var is set:

echo $API_TOKEN

2. Verify your config syntax:

[fetch]
# Both formats work:
headers = { Authorization = "Bearer $API_TOKEN" }
headers = { Authorization = "Bearer ${API_TOKEN}" }

3. Export the variable before running:

export API_TOKEN="your-token"
chowbea-axios fetch

Generation Failed with openapi-typescript Error

Symptom: Error mentioning openapi-typescript during generation.

Solution: The CLI uses pnpm dlx openapi-typescript internally. Make sure:

1. You have pnpm installed (or npm/npx available)
2. Your OpenAPI spec is valid JSON/YAML

Validate your spec first:

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)