Troubleshooting Documentation

Solutions to common issues and debugging guides for the Aitana Labs frontend.

Available Guides

• Langfuse Troubleshooting
• Tool Confirmation Bug Fix

Common Issues

Build Errors

• Check npm run quality:check for full CI simulation
• Run npm run docker:check to test Docker build
• Use CI=true npm run test:run to debug CI-only failures

Test Failures

• Ensure all hooks are called before conditionals
• Check for missing TypeScript types
• Verify mocks match actual component interfaces

Development Environment

• Node version: Use nvm use to switch to v18
• Port conflicts: Kill processes using required ports
• Firebase emulators: Check if already running

Getting Help

If you encounter issues not covered here:

1. Check the Development Documentation
2. Review recent commits for similar issues
3. Search existing GitHub issues
4. Create a new issue with detailed reproduction steps