Skip to main content

​
Common Issues

Find solutions to frequently encountered problems when developing with and running the Nadoo AI platform.
Symptom: The frontend or backend fails to start with an EADDRINUSE or Address already in use error.Solution: Identify and terminate the process occupying the port.
# Kill the process on port 3000 (frontend)
lsof -ti:3000 | xargs kill -9

# Kill the process on port 8000 (backend)
lsof -ti:8000 | xargs kill -9
Then restart the service:
# Restart the full platform
npm run start
If you frequently run into port conflicts, you can configure alternative ports in your .env file using FRONTEND_PORT and BACKEND_PORT.
Symptom: Commands fail with Cannot connect to the Docker daemon or docker: command not found.Solution: Verify that Docker is installed and the daemon is running.
# Check Docker status
docker info
If Docker is not running:
  • macOS / Windows: Open Docker Desktop and wait for it to fully start (the whale icon should be steady, not animating).
  • Linux: Start the Docker daemon with sudo systemctl start docker.
Verify Docker Compose is available:
docker compose version
Nadoo AI requires Docker Engine 20.10+ and Docker Compose V2.
Symptom: Errors like Failed building wheel, error: command 'gcc' failed, or missing headers during pip install.Solution: Install the required build tools for your operating system.
# Install Xcode command-line tools
xcode-select --install

# If using Homebrew, also install:
brew install postgresql libffi
After installing build tools, retry the installation:
cd packages/backend
pip install -r requirements.txt
Symptom: Errors related to missing tables, columns, or Alembic revision conflicts when starting the backend.Solution: Run the Alembic migration to bring the database schema up to date.
cd packages/backend
alembic upgrade head
If you encounter a revision conflict:
# Check current migration state
alembic current

# View migration history
alembic history --verbose

# If the database is out of sync, stamp the current revision
alembic stamp head
Never manually edit migration files in packages/backend/migrations/versions/. Always use the Alembic CLI to generate and apply migrations. See the development guide for the correct workflow.
Symptom: ConnectionRefusedError: [Errno 111] Connection refused or Error 61 connecting to localhost:6379.Solution: Redis is required for task queuing, caching, and real-time features. Check that the Redis container is running.
# Check if Redis container is running
docker ps | grep redis

# If not running, start it via Docker Compose
docker compose up -d redis

# Test the connection
docker compose exec redis redis-cli ping
# Expected output: PONG
Verify the Redis connection URL in your .env file:
REDIS_URL=redis://localhost:6379/0
If Redis is running inside Docker but the backend is running natively (outside Docker), ensure you are connecting to the correct host. Use localhost if ports are mapped, or the Docker network hostname if both services are in Docker.
Symptom: Module not found, Cannot resolve dependency, or other build failures when starting the Next.js frontend.Solution: Clean and reinstall dependencies.
cd packages/frontend

# Remove existing node_modules and lock file
rm -rf node_modules
rm -f package-lock.json

# Reinstall dependencies
npm install

# Restart the dev server
npm run dev
If the error persists, clear the Next.js cache:
rm -rf .next
npm run dev
Nadoo AI requires Node.js 18+ and npm 9+. Check your version with node --version and npm --version.
Symptom: AuthenticationError, Invalid API key, or 401 Unauthorized when the AI agent attempts to call a model.Solution:
  1. Check your .env file for the correct environment variable:
# OpenAI
OPENAI_API_KEY=sk-...

# Anthropic
ANTHROPIC_API_KEY=sk-ant-...

# Azure OpenAI
AZURE_OPENAI_API_KEY=...
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/

# AWS Bedrock
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
AWS_REGION=us-east-1
  1. Verify the key is valid by testing it directly:
# Test OpenAI key
curl -s https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY" | head -c 200
  1. Restart the backend after changing environment variables:
# If using Docker Compose
docker compose restart backend
You can also configure API keys through the platform UI at Workspace Settings > AI Model Providers without modifying the .env file.
Symptom: Browser console shows Access to fetch at 'http://localhost:8000/...' from origin 'http://localhost:3000' has been blocked by CORS policy.Solution: Ensure the frontend origin is listed in the backend’s CORS configuration.In your .env file:
# Allow the frontend origin
CORS_ORIGINS=http://localhost:3000,http://127.0.0.1:3000

# For development, you can allow all origins (not recommended for production)
# CORS_ORIGINS=*
Restart the backend after updating:
docker compose restart backend
Never use CORS_ORIGINS=* in production. Always specify the exact origins that should be allowed.
Symptom: Chat messages do not stream in real time, the connection indicator shows “disconnected”, or the browser console shows WebSocket errors.Solution:
  1. Ensure the backend is running and accessible:
curl http://localhost:8000/health
  1. Check WebSocket proxy settings. If you are using a reverse proxy (Nginx, Caddy, Traefik), ensure it is configured to proxy WebSocket connections:
# Nginx example
location /ws {
    proxy_pass http://backend:8000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
}
  1. Check the WebSocket URL in your frontend environment:
NEXT_PUBLIC_WS_URL=ws://localhost:8000/ws
  1. Firewall and network: Ensure port 8000 is open and WebSocket traffic is not being blocked by a corporate firewall or VPN.

​
Debugging Techniques

​
Enable Debug Logging

Set the log level to DEBUG for more detailed output from the backend: 
LOG_LEVEL=DEBUG

docker compose restart backend
# Then view logs
docker compose logs -f backend

​
Inspect Docker Containers

# View status of all containers
docker compose ps

# View logs for a specific service
docker compose logs -f backend
docker compose logs -f worker
docker compose logs -f skill-worker

# Access a container shell
docker compose exec backend bash

​
Check Database State

# Connect to PostgreSQL
docker compose exec postgres psql -U nadoo -d nadoo

# Check Alembic migration version
docker compose exec backend alembic current

​
Getting Help

If you are still stuck after trying the solutions above:
1

Search the Documentation

Review the FAQ, Glossary, and relevant feature pages for additional context.
2

Check GitHub Issues

Search GitHub Issues for similar problems and existing solutions.
3

Ask the Community

Join our Discord and describe your issue in the support channel.
4

Open a Bug Report

If the issue is new, open a GitHub issue with:
  • The exact error message and stack trace
  • Steps to reproduce
  • Your environment (OS, Docker version, Node.js version, Python version)
  • Relevant .env settings (with secrets redacted)

​
Next Steps

FAQ

Frequently asked questions about the platform

Self-Hosting Guide

Deployment and configuration reference

Environment Variables

Complete list of configuration options

Core Concepts

Core concepts for building with Nadoo AI