Référence
Dépannage
Codes d'Erreur

Codes d'Erreur

Référence complète des codes d'erreur CSWeb Community Platform avec solutions.

Erreurs Database

DB-001: Connection Refused

Message :

SQLSTATE[08006] Connection refused

Causes :

  • Service PostgreSQL/MySQL non démarré
  • Port incorrect (5432/3306)
  • Host incorrect (localhost vs postgres)

Solutions :

# Vérifier service
docker compose ps postgres
 
# Restart
docker compose restart postgres
 
# Vérifier .env
POSTGRES_HOST=postgres  # Nom service Docker
POSTGRES_PORT=5432

DB-002: Authentication Failed

Message :

SQLSTATE[28P01] password authentication failed for user "csweb"

Causes :

  • Password incorrect dans .env
  • User n'existe pas
  • pg_hba.conf mal configuré

Solutions :

# Vérifier credentials
echo $POSTGRES_USER
echo $POSTGRES_PASSWORD
 
# Reset password
docker compose exec postgres psql -U postgres -c \
  "ALTER USER csweb_analytics PASSWORD 'new_password';"

DB-003: Database Does Not Exist

Message :

SQLSTATE[3D000] database "csweb_analytics" does not exist

Solutions :

# Créer database
docker compose exec postgres psql -U postgres -c \
  "CREATE DATABASE csweb_analytics OWNER csweb_analytics;"
 
# Ou rebuild
docker compose down -v
docker compose up -d

DB-004: Driver Not Found

Message :

could not find driver pdo_pgsql

Causes :

  • Extension PDO non installée
  • Driver SQL Server non installé

Solutions :

# PostgreSQL
apt-get install php8.1-pgsql
php -m | grep pdo_pgsql
 
# MySQL
apt-get install php8.1-mysql
 
# SQL Server
./install-sqlsrv-driver.sh

DB-005: Connection Pool Exhausted

Message :

FATAL: sorry, too many clients already

Solutions :

-- PostgreSQL: Augmenter max_connections
ALTER SYSTEM SET max_connections = 200;
SELECT pg_reload_conf();
 
-- Vérifier connexions actives
SELECT count(*) FROM pg_stat_activity;

Erreurs Breakout

BRK-001: Dictionary Not Found

Message :

Dictionary 'EVAL_DICT' not found in CSPro server

Causes :

  • Dictionnaire non uploadé
  • Nom incorrect (case-sensitive)
  • CSPro server inaccessible

Solutions :

# Vérifier dictionnaires disponibles
curl -X GET http://localhost:8080/api/dictionaries
 
# Uploader dictionnaire
curl -X POST http://localhost:8080/api/dictionaries \
  -F "file=@survey.dcf"

BRK-002: Breakout Failed

Message :

Breakout process terminated with exit code 1

Causes :

  • Table déjà existe
  • Permission denied sur DB
  • Schema invalide

Solutions :

# Vérifier logs
docker compose logs csweb | grep -A 10 "Breakout"
 
# Drop table existante
DROP TABLE IF EXISTS eval_dict_producteurs;
 
# Vérifier permissions
GRANT ALL ON SCHEMA public TO csweb_analytics;

BRK-003: Case Parse Error

Message :

Failed to parse case data: Invalid JSON

Solutions :

# Vérifier format case
cat case.json | jq .
 
# Re-synchroniser CSPro
curl -X POST http://cspro-server/api/sync

BRK-004: Table Already Exists

Message :

Table 'eval_dict_level_1' already exists

Solutions :

# Drop tables
php bin/console csweb:drop-breakout-tables EVAL_DICT
 
# Ou force overwrite
php bin/console csweb:process-cases-by-dict EVAL_DICT --force

Erreurs OAuth2

AUTH-001: Invalid Credentials

Message :

{
  "error": "invalid_grant",
  "error_description": "Invalid username or password"
}

Solutions :

# Vérifier user existe
SELECT username, enabled FROM users WHERE username = 'admin';
 
# Reset password
php bin/console security:encode-password newpassword
UPDATE users SET password = 'HASH' WHERE username = 'admin';

AUTH-002: Invalid Client

Message :

{
  "error": "invalid_client",
  "error_description": "Client credentials are invalid"
}

Solutions :

# Vérifier .env
echo $OAUTH_CLIENT_ID
echo $OAUTH_CLIENT_SECRET
 
# Recreate client
php bin/console oauth:client:create

AUTH-003: Token Expired

Message :

{
  "error": "invalid_token",
  "error_description": "The access token provided has expired"
}

Solutions :

# Regénérer token
curl -X POST http://localhost:8080/api/token \
  -d "grant_type=password" \
  -d "username=admin" \
  -d "password=admin123"

AUTH-004: Insufficient Permissions

Message :

{
  "error": "access_denied",
  "error_description": "You do not have permission to access this resource"
}

Solutions :

-- Vérifier rôles user
SELECT username, roles FROM users WHERE username = 'admin';
 
-- Ajouter rôle ADMIN
UPDATE users SET roles = '["ROLE_ADMIN"]' WHERE username = 'admin';

Erreurs API

API-001: Method Not Allowed

Message :

{
  "error": "Method POST not allowed for this route"
}

Solutions :

# Vérifier méthode HTTP
curl -X GET http://localhost:8080/api/dictionaries  # Correct
curl -X POST http://localhost:8080/api/dictionaries  # Incorrect

API-002: Resource Not Found

Message :

{
  "error": "Dictionary 'UNKNOWN' not found"
}

Solutions :

# Lister ressources disponibles
curl -X GET http://localhost:8080/api/dictionaries
curl -X GET http://localhost:8080/api/breakout/jobs

API-003: Invalid JSON

Message :

{
  "error": "Syntax error in JSON payload"
}

Solutions :

# Valider JSON
echo '{"key": "value"}' | jq .
 
# Correct request
curl -X POST http://localhost:8080/api/webhooks \
  -H "Content-Type: application/json" \
  -d '{"event": "case_uploaded", "dictionary": "EVAL_DICT"}'

API-004: Rate Limit Exceeded

Message :

{
  "error": "Too many requests",
  "retry_after": 60
}

Solutions :

# Attendre 60 secondes
sleep 60
 
# Ou augmenter limite (config/packages/rate_limiter.yaml)
limit: 100
interval: '1 minute'

Erreurs Docker

DCK-001: Port Already in Use

Message :

Error: bind: address already in use 0.0.0.0:8080

Solutions :

# Trouver processus
lsof -i :8080
netstat -tuln | grep 8080
 
# Kill processus
kill -9 <PID>
 
# Ou changer port
CSWEB_PORT=8081
docker compose up -d

DCK-002: Volume Permission Denied

Message :

Permission denied: '/var/lib/postgresql/data'

Solutions :

# Fix permissions
sudo chown -R 999:999 ./postgres-data
 
# Ou recreate volume
docker compose down -v
docker compose up -d

DCK-003: Out of Memory

Message :

Container killed (OOMKilled)

Solutions :

# Augmenter mémoire
docker-compose.yml:
  csweb:
    mem_limit: 2g
    mem_reservation: 1g
 
# Vérifier usage
docker stats

DCK-004: Network Not Found

Message :

network csweb_default not found

Solutions :

# Recreate network
docker compose down
docker compose up -d
 
# Ou créer manuellement
docker network create csweb_default

Erreurs Webhooks (racine)

Les 4 webhooks PHP racine (breakout-webhook.php, breakout-status-webhook.php, dictionary-schema-webhook.php, log-reader-webhook.php) partagent un format de réponse uniforme et un catalogue de codes d'erreur stable :

{ "success": false, "data": null, "error": { "code": "<id>", "message": "<description>" } }

WHK-001 : missing_token / invalid_token (HTTP 401)

Réponse :

{
  "success": false,
  "data": null,
  "error": {
    "code": "missing_token",
    "message": "Missing or invalid Authorization header. Expected: Bearer <token>."
  }
}

Solutions :

# Vérifier que la variable est définie côté serveur CSWeb
docker exec csweb-app printenv BREAKOUT_WEBHOOK_TOKEN
 
# Vérifier que le client envoie exactement la même valeur
curl -H "Authorization: Bearer <token>" http://csweb.example.com/breakout-status-webhook.php
 
# Régénérer un token solide
openssl rand -hex 32

WHK-002 : server_misconfigured (HTTP 500)

Réponse :

{
  "success": false,
  "data": null,
  "error": {
    "code": "server_misconfigured",
    "message": "Server misconfiguration: BREAKOUT_WEBHOOK_TOKEN environment variable is not set."
  }
}

Solutions :

# Définir la variable dans .env
echo "BREAKOUT_WEBHOOK_TOKEN=$(openssl rand -hex 32)" >> .env
 
# Recréer le container csweb pour qu'il pick up la variable
docker compose up -d --no-deps csweb

WHK-003 : rate_limited (HTTP 429)

Réponse :

{
  "success": false,
  "data": null,
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Retry after 42 seconds."
  }
}

Header HTTP additionnel : Retry-After: 42

Solutions :

  • Espacer les appels (limite : 60 req / 60 s par couple (token, IP)).
  • Honorer le header Retry-After côté client.
  • Si vous orchestrez plusieurs équipes derrière la même IP, segmenter par IP source.

WHK-004 : invalid_body / invalid_dictionary / invalid_filename (HTTP 400)

Réponse (exemple invalid_dictionary) :

{
  "success": false,
  "data": null,
  "error": {
    "code": "invalid_dictionary",
    "message": "Invalid dictionary name. Must match: ^[A-Z0-9_]+$."
  }
}

Solutions :

# Payload correct pour breakout-webhook.php
curl -X POST http://csweb.example.com/breakout-webhook.php \
  -H "Authorization: Bearer $BREAKOUT_WEBHOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"dictionary": "EVAL_DICT"}'
 
# Payload correct pour dictionary-schema-webhook.php (par dict_name)
curl -X POST http://csweb.example.com/dictionary-schema-webhook.php \
  -H "Authorization: Bearer $BREAKOUT_WEBHOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "register",
    "dictionary_name": "EVAL_DICT",
    "host_name": "host.docker.internal",
    "schema_name": "eval_breakout",
    "schema_user_name": "csweb",
    "schema_password": "secret"
  }'

WHK-005 : body_too_large (HTTP 413)

Le body POST est limité à 64 KB sur tous les webhooks. Au-delà, la requête est rejetée avant parsing JSON.

Solutions : vérifier la taille du payload côté client. Si vous batchez plusieurs registers, faites-les en boucle plutôt qu'en un seul appel.

WHK-006 : breakout_failed (HTTP 500)

Renvoyé par breakout-webhook.php quand le process Symfony termine avec un exit code non-zéro. Le payload data.exitCode indique le code, et data.output / data.stderr contiennent les 4 derniers KB de sortie (par défaut). Pour le contenu complet, consulter le fichier listé dans data.logFile ou activer BREAKOUT_WEBHOOK_VERBOSE=1.

# Lire le log complet d'un breakout via le webhook log-reader
curl -H "Authorization: Bearer $BREAKOUT_WEBHOOK_TOKEN" \
  "http://csweb.example.com/log-reader-webhook.php?file=EVAL_DICT_20260419_103000-api.log&lines=2000"

Erreurs Performance

PERF-001: Slow Query

Message :

Query took 15.3 seconds to execute

Solutions :

-- Créer index
CREATE INDEX idx_case_id ON eval_dict_level_1(case_id);
CREATE INDEX idx_verified ON eval_cases(verified);
 
-- Analyser query
EXPLAIN ANALYZE SELECT * FROM eval_dict_level_1 WHERE case_id = '123';

PERF-002: Memory Limit Exceeded

Message :

PHP Fatal error: Allowed memory size exhausted

Solutions :

# php.ini
memory_limit = 512M
 
# Ou pour une commande
php -d memory_limit=1G bin/console csweb:process-cases-by-dict EVAL_DICT

Codes HTTP

CodeSignificationAction
400Bad RequestVérifier payload JSON
401UnauthorizedRegénérer token OAuth
403ForbiddenVérifier rôles user
404Not FoundVérifier URL/resource existe
429Too Many RequestsAttendre rate limit reset
500Internal Server ErrorVérifier logs serveur
502Bad GatewayVérifier service backend running
503Service UnavailableAttendre service redémarre

Logs Debug

Activer Logs Détaillés

# .env
APP_ENV=dev
APP_DEBUG=true
LOG_LEVEL=debug

Tail Logs

# Tous les logs
docker compose logs -f
 
# Service spécifique
docker compose logs -f csweb
 
# Filtrer erreurs
docker compose logs csweb | grep ERROR

Logs PostgreSQL

# Activer slow query log
ALTER SYSTEM SET log_min_duration_statement = 1000;
SELECT pg_reload_conf();
 
# Voir logs
docker compose exec postgres tail -f /var/lib/postgresql/data/log/postgresql.log

Ressources

FAQChangelog