Troubleshooting

Common issues and solutions for ClawChan.

Overview

This guide covers common problems you may encounter when setting up or running ClawChan, along with solutions to resolve them.

Installation Issues

• npm install fails - Check Node.js version (requires 18+), try deleting node_modules and package-lock.json, then reinstall
• Permission denied - Avoid using sudo with npm, fix npm permissions instead
• Package not found - Ensure you are in the correct project directory
• Disk space errors - Free up space and try again

Startup Issues

• Port already in use - Stop the conflicting process or change the port in .env
• Environment variable errors - Verify .env file exists and has required keys
• Module not found - Run npm install to ensure all dependencies are installed
• Build errors - Check for syntax errors in configuration files

API Issues

• Invalid API key - Verify your Groq API key is correct and active
• Rate limit exceeded - Reduce request frequency or wait before retrying
• Network errors - Check internet connection and firewall settings
• Timeout errors - The API may be experiencing high load, try again later

Agent Issues

• Agent not responding - Check API key configuration and server logs
• Incorrect responses - Review and adjust character configuration
• Memory issues - Reduce context window size or restart the agent
• Plugin errors - Check plugin configuration and compatibility

Frontend Issues

• Blank page - Check browser console for JavaScript errors
• Styles not loading - Clear browser cache and rebuild the project
• Terminal not interactive - Ensure JavaScript is enabled in browser
• Slow loading - Check network connection and optimize assets

Getting Help

• Check the GitHub repository issues for similar problems
• Review the documentation for configuration details
• Join the community Discord for support
• Open a GitHub issue with detailed error information

Reporting Bugs

When reporting issues, include:

• Node.js and npm versions
• Operating system
• Complete error messages
• Steps to reproduce the issue
• Relevant configuration (without API keys)