Troubleshooting

Common issues and solutions when using nuxt-openapi-hyperfetch.

Quick Diagnosis

Generation Issues

• CLI won't run → Build Issues
• OpenAPI parsing fails → Generation Errors
• Generated code has errors → Type Errors

Runtime Issues

• Composables not working → Composables Issues
• Server errors → Server Issues
• API calls failing → Runtime Errors

Performance Issues

• Slow generation → Performance
• Large bundle size → Performance

Common Problems

1. CLI Command Not Found

nxh: command not found

Solution:

# Install globally
npm install -g nuxt-openapi-hyperfetch

# Or use npx
npx nuxt-openapi-hyperfetch generate -i swagger.yaml

2. Generation Fails

Error: Failed to parse OpenAPI specification

Solution:

• Validate your OpenAPI spec: Generation Errors
• Check file path is correct
• Ensure spec is valid OpenAPI 3.0

3. TypeScript Errors

Type 'unknown' is not assignable to type 'Pet'

Solution:

• Regenerate types after spec changes
• Check Type Errors

4. Composables Not Found

Cannot find module '~/composables/pets'

Solution:

• Ensure generation completed successfully
• Check output directory matches import path
• Restart Nuxt dev server

5. API Calls Fail

404 Not Found
CORS error

Solution:

• Configure correct baseURL
• Check Runtime Errors
• Verify API endpoint is accessible

By Category

Generation & Build

Issue	Guide
OpenAPI parsing errors	Generation Errors
TypeScript compilation fails	Type Errors
Build failures	Build Issues
Slow generation	Performance

Client Composables

Issue	Guide
useFetch not working	Composables Issues
Type errors in components	Composables Issues
Data not reactive	Composables Issues
Callbacks not firing	Composables Issues

Server Composables

Issue	Guide
H3Event errors	Server Issues
Auth not working	Server Issues
Headers not forwarded	Server Issues
Server errors	Server Issues

Runtime

Issue	Guide
Network errors	Runtime Errors
CORS issues	Runtime Errors
401/403 errors	Runtime Errors
Timeout errors	Runtime Errors

Getting Help

If you can't find a solution:

1. Search Issues - Check GitHub Issues
2. Ask Community - Post in GitHub Discussions
3. Join Discord - Get help in #support channel
4. Create Issue - Report bug with reproduction

Creating a Good Bug Report

Include:

**Environment:**
- OS: Windows 11
- Node: v20.10.0
- nuxt-openapi-hyperfetch: v1.2.0
- Nuxt: v3.10.0

**OpenAPI Spec:**
```yaml
# Minimal spec that reproduces issue

Steps to Reproduce:

1. Run nxh generate -i spec.yaml
2. Import generated composable
3. See error

Expected: Should generate valid composable

Actual: Error: ...

Error Output:

## Debug Mode

Enable verbose logging:

```bash
# Set debug environment variable
DEBUG=nxh:* nxh generate -i swagger.yaml

# Or use verbose flag (if available)
nxh generate -i swagger.yaml --verbose

Next Steps

Choose your issue category:

• Generation Errors →
• Composables Issues →
• Server Issues →
• Type Errors →
• Build Issues →
• Runtime Errors →
• Performance →