Dépannage

Solutions aux problèmes les plus fréquents rencontrés en développement.

Installation et setup

uv sync échoue avec une erreur de version Python

Cause : Python 3.13+ est requis. uv ne trouve pas la bonne version.

Solution :

# Vérifier la version
python --version

# Si < 3.13, installer via uv
uv python install 3.13

# Puis relancer
cd services/core && uv sync

pnpm install échoue avec des erreurs de peer dependencies

Cause : Version de pnpm ou Node.js incompatible.

Solution :

# Vérifier les versions
node -v   # Doit être 20+
pnpm -v   # Doit être 9+

# Mettre à jour pnpm
corepack prepare pnpm@latest --activate

# Nettoyer et réinstaller
rm -rf node_modules
pnpm install

Port déjà utilisé au lancement

Cause : Un service précédent n'a pas été arrêté proprement.

Solution :

# Trouver le processus sur le port (Windows)
netstat -ano | findstr :8000
taskkill /PID <PID> /F

# macOS/Linux
lsof -i :8000
kill -9 <PID>

Base de données

alembic upgrade head échoue

Cause possible 1 : La base SQLite n'existe pas encore.

# Créer le dossier data s'il n'existe pas
mkdir -p data
cd services/core && uv run alembic upgrade head

Cause possible 2 : PostgreSQL non démarré (si USE_SQLITE=false).

docker compose up -d postgres

Erreur "relation does not exist"

Cause : Migrations pas à jour.

cd services/core && uv run alembic upgrade head

Authentification

401 Unauthorized en mode dev

Cause : Le header X-Tenant-ID est manquant. Même en mode dev (sans JWT), ce header est obligatoire.

Solution :

curl -H "X-Tenant-ID: your-tenant-uuid" http://localhost:8000/api/flows

403 Forbidden — Tenant non autorisé

Cause : Le X-Tenant-ID fourni n'est pas dans la liste des tenants autorisés du JWT.

Solution : Vérifier le contenu du JWT (utiliser jwt.io pour décoder) et s'assurer que tenant_ids ou organization_id contient le tenant demandé.

Python / Backend

Erreur de caractères non-ASCII dans les logs (Windows)

Cause : Windows PowerShell ne supporte pas l'encodage UTF-8 par défaut. Les émojis ou accents dans les messages de log provoquent un UnicodeEncodeError.

Solution :

1. Ne jamais utiliser d'émojis ou de caractères non-ASCII dans les messages de log.
2. Configurer PowerShell :

[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
$env:PYTHONIOENCODING = "utf-8"

ModuleNotFoundError pour un package Python

Cause : Le virtualenv n'est pas activé, ou uv sync n'a pas été exécuté.

cd services/core
uv sync
uv run python -c "import fastapi; print('OK')"

Erreur d'import circulaire

Cause : Violation de l'architecture hexagonale — un module domain importe depuis infrastructure.

Solution : Vérifier la direction des imports. Le domaine ne doit importer que du Python standard.

Frontend

Erreur d'hydratation Next.js

Cause : Le HTML rendu côté serveur ne correspond pas au rendu côté client. Fréquent avec des composants qui dépendent de window, localStorage, ou de l'heure locale.

Solution : Envelopper ces composants dans un useEffect ou utiliser next/dynamic avec ssr: false.

Le hot reload ne fonctionne pas

Cause possible : Turborepo cache un état obsolète.

# Nettoyer le cache Turbo
rm -rf .turbo
pnpm dev

Erreur de build "Module not found" pour @naixus/shared

Cause : Le package partagé n'a pas été buildé.

pnpm build --filter=@naixus/shared

LLM et intégrations

Rate limit exceeded d'un fournisseur LLM

Cause : Trop de requêtes en développement.

Solutions :

• Utiliser Ollama en local (pas de rate limit).
• Réduire la fréquence des tests manuels.
• Configurer un autre fournisseur dans Settings > Integrations.

L'agent ne répond pas (timeout)

Cause possible : Le fournisseur LLM est inaccessible ou la clé API est invalide.

Vérification :

# Tester directement l'API OpenAI
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

Ollama ne se connecte pas

Cause : L'URL de base est mal configurée.

Solution : Vérifier que Ollama est lancé et accessible :

curl http://localhost:11434/api/tags

Configurer dans .env :

OLLAMA_BASE_URL=http://localhost:11434

Collaboration temps réel (Yjs)

Les modifications ne se synchronisent pas entre navigateurs

Cause : Le Yjs Server n'est pas lancé.

# Vérifier que le port 1234 est ouvert
curl http://localhost:1234

Si le serveur n'est pas lancé, pnpm dev devrait le démarrer. Sinon :

cd apps/yjs_server && pnpm dev

Git et CI

Pre-commit hook échoue

Cause : Les hooks commitlint ou lint-staged rejettent le commit.

Solution :

# Vérifier le message de commit
echo "feat(flows): add export" | npx commitlint

# Vérifier le linting
pnpm lint:fix
cd services/core && uv run ruff check --fix .

Ne jamais utiliser --no-verify pour contourner les hooks.