Troubleshooting

Common issues and solutions for the api-docs CLI.

Browser/Puppeteer Issues

"Could not find Chrome"

Puppeteer needs a Chromium browser to extract documentation from JavaScript-rendered pages.

Solutions:

1. Let Puppeteer download its own browser:

   npx puppeteer browsers install chrome

2. Use a system-installed Chrome:

   export PUPPETEER_EXECUTABLE_PATH=/path/to/chrome

3. Install Chromium via your package manager:

   # macOS
   brew install chromium
   
   # Ubuntu/Debian
   sudo apt install chromium-browser
   
   # Windows (via Chocolatey)
   choco install chromium

Browser timeout errors

If extraction times out, the page may be slow to load or blocking automated browsers.

Solutions:

1. Try a direct URL to the OpenAPI spec instead:

   api-docs endpoints https://api.example.com/openapi.json

2. Check if the site requires authentication or has bot protection

3. Ensure stable network connection

Extraction Failures

"No API documentation found"

The CLI couldn't extract endpoints from the provided URL.

Possible causes:

1. Not an API docs page - The URL doesn't contain OpenAPI/Swagger documentation
2. Unsupported format - The documentation uses a framework we don't support yet
3. JavaScript required - The page needs JavaScript but Puppeteer failed

Solutions:

1. Try the direct OpenAPI spec URL if available:

   api-docs endpoints https://api.example.com/openapi.yaml

2. Use a different URL format:

   # Instead of docs homepage
   api-docs endpoints https://docs.example.com/api/reference

3. Check if the API publishes its spec file location in their docs

"OpenAPI extraction failed"

The URL was detected as an OpenAPI spec but couldn't be parsed.

Possible causes:

1. Invalid OpenAPI/Swagger syntax
2. YAML parsing error
3. Network error during fetch

Solutions:

1. Verify the spec URL is accessible in a browser
2. Check if the spec is valid using Swagger Editor
3. Try fetching again with --force:

   api-docs fetch https://api.example.com/openapi.json --force

Provider Lookup Issues

"No API found for provider"

The provider name wasn't found in APITracker.io.

Solutions:

1. Check the provider name spelling
2. Try variations (e.g., "github" vs "GitHub")
3. Use the direct docs URL instead:

   api-docs endpoints https://docs.provider.com/api

"Failed to search APITracker"

Network error when contacting APITracker.io.

Solutions:

1. Check your internet connection
2. APITracker.io may be temporarily down - try again later
3. Use a direct URL as a workaround

Cache Issues

Stale or incorrect cached data

Clear the cache and fetch fresh:

# Clear all caches
api-docs clear

# Or clear specific cache
api-docs clear https://api.example.com/openapi.json

# Fetch fresh
api-docs endpoints stripe --force

Cache directory permissions

If you see permission errors:

# Check cache directory
ls -la ~/.cache/api-docs-cli/

# Fix permissions if needed
chmod -R u+rw ~/.cache/api-docs-cli/

Node.js Issues

"Unsupported engine" warning

The CLI requires Node.js 20.0.0 or higher.

Solution:

Update Node.js:

# Using nvm
nvm install 20
nvm use 20

# Or download from nodejs.org

Module errors

If you see ES module errors:

1. Ensure you're using Node.js 20+
2. Try reinstalling:

   npm uninstall -g @tidalstudios/api-docs-cli
   npm install -g @tidalstudios/api-docs-cli

Getting Help

If you encounter an issue not covered here:

1. Check the GitHub Issues
2. Open a new issue with:
   • Command you ran
   • Error message
   • Node.js version (node --version)
   • Operating system