# Dépannage Les erreurs que tu risques le plus de rencontrer au démarrage de Sovrium, leur cause, et comment les corriger. Chaque entrée cite le **message réel** affiché par Sovrium, pour que tu puisses le retrouver dans ton terminal. Si tu bloques sur une configuration, lance d'abord `sovrium validate ` : la commande vérifie ton fichier de façon isolée et affiche précisément ce qui ne va pas. ## Le serveur a démarré sur un autre port ```text [SERVER] Port 3000 in use; using an OS-assigned port (see URL below). ``` Un autre processus occupe déjà le port : Sovrium démarre donc sur un port libre au lieu d'échouer. Lis l'URL affichée au démarrage pour trouver la vraie adresse, ou choisis toi-même un port libre : ```bash PORT=4000 sovrium start app.yaml ``` Un `PORT` hors limites est rejeté directement : ```text Error: Invalid port number "99999". Must be between 0 and 65535 (0 = auto-select). ``` ## « Server already running » ```text Error: Server already running (PID: 12345, port: 3000) ``` Une instance Sovrium tourne déjà (Sovrium la suit avec un fichier de verrou). Arrête-la d'abord : ```bash sovrium stop ``` Un verrou obsolète laissé par un processus planté (dont le PID n'existe plus) est détecté et supprimé automatiquement : ce message ne t'arrête donc que si une instance tourne réellement. ## « Unsupported DATABASE_URL scheme » ```text Unsupported DATABASE_URL scheme: "./data/app.db". Use postgres://, postgresql://, file:, sqlite:, or :memory:. A bare filesystem path is not accepted — prefix it with file: (e.g. file:./database.db). ``` `DATABASE_URL` est définie mais n'a pas un schéma reconnu — l'erreur classique est un simple chemin de fichier. Tu as trois bonnes options : - **Laisse `DATABASE_URL` vide.** Sovrium utilise alors une base SQLite embarquée sans aucune configuration — c'est le comportement par défaut, sans serveur à installer. - **Pointe vers un fichier SQLite** en préfixant le chemin par `file:` — `file:./database.db`. - **Utilise PostgreSQL** avec une URL complète — `postgres://user:password@localhost:5432/app`. :::callout **SQLite est le choix par défaut, sans configuration.** Sans `DATABASE_URL`, Sovrium stocke les données dans un fichier SQLite local — les tables et l'authentification fonctionnent d'emblée, rien à installer. Ne définis `DATABASE_URL` que pour choisir l'emplacement du fichier ou passer à PostgreSQL. Voir [Infrastructure de base de données](/fr/docs/database-infrastructure). ::: ## « Validation failed » (erreurs de configuration) `sovrium validate` — et chaque démarrage — vérifie ta configuration face au schéma. En cas d'échec, tu obtiens l'arbre des problèmes exacts sous un seul en-tête : ```text Validation failed: ``` Deux cas que tu peux voir dans cet arbre : - `Unknown field type "colour" in field "status"` — un champ de table utilise un type qui n'existe pas. Voir [Aperçu des types de champs](/fr/docs/field-types-overview) pour l'ensemble valide. - `Action "..." ... uses "type: cloud", which requires the Sovrium Cloud host gate (SOVRIUM_CLOUD_MODE). This config is not running in cloud mode.` — une action « cloud » ne peut pas s'exécuter dans le binaire auto-hébergé. Un fichier valide affiche `Valid configuration: ` et se termine proprement. ## « SOVRIUM_ENCRYPTION_KEY is required » ```text SOVRIUM_ENCRYPTION_KEY is required. Generate a strong random value (e.g. `openssl rand -base64 32`) and set it in the deployment environment, or set SOVRIUM_ALLOW_DEV_KEY=1 to use the deterministic dev fallback for local development only. ``` Une fonctionnalité qui chiffre des secrets stockés — comme les jetons de connexion OAuth — a besoin d'une clé de chiffrement. Génères-en une et définis-la : ```bash sovrium secret generate # affiche SOVRIUM_ENCRYPTION_KEY=<64-hex> # ou : openssl rand -base64 32 ``` Pour le développement local uniquement, tu peux contourner la gestion de clé avec `SOVRIUM_ALLOW_DEV_KEY=1`, qui utilise une clé jetable déterministe. :::callout **N'utilise jamais la clé de dev en production.** `SOVRIUM_ALLOW_DEV_KEY` existe pour le travail local. Un vrai déploiement doit définir une `SOVRIUM_ENCRYPTION_KEY` forte et secrète. ::: ## « File not found » ou « No configuration provided » ```text Error: File not found: app.yaml ``` Le chemin de configuration n'existe pas — vérifie le nom et le dossier. Messages liés : - `Error: No configuration provided` — tu as lancé une commande sans fichier de config ni `APP_SCHEMA`. Passe un fichier : `sovrium start app.yaml`. - `Error: Unsupported file format: .toml` — Sovrium lit `.json`, `.yaml`, `.yml` et `.ts`. ## « Failed to parse » ta configuration ```text Error: Failed to parse YAML file: app.yaml Details: ``` Une erreur de syntaxe dans le fichier. La cause classique : des **tabulations dans un fichier YAML** — l'indentation YAML doit utiliser des espaces, jamais des tabulations. Lis la ligne `Details:` pour l'emplacement exact, corrige, puis relance `sovrium validate app.yaml`. Les configs TypeScript affichent plutôt `Failed to load TypeScript file` (une erreur de type ou d'import). ## Auth : « You are using the default secret » ```text You are using the default secret. Please set `BETTER_AUTH_SECRET` in your environment variables or pass `secret` in your auth config. ``` En production (`NODE_ENV=production`), une application avec authentification a besoin d'un vrai secret. En développement, elle retombe sur un secret de dev intégré et se contente d'un avertissement — ce message apparaît donc au déploiement. Génères-en un : ```bash sovrium secret generate auth # affiche AUTH_SECRET=<64-hex> ``` :::callout **La variable est `AUTH_SECRET`.** Le message de la bibliothèque d'authentification sous-jacente nomme `BETTER_AUTH_SECRET`, mais Sovrium lit `AUTH_SECRET`. C'est celle-là qu'il faut définir. ::: ## « Email sending disabled — SMTP not configured » ```text Email sending disabled — SMTP not configured (set SMTP_HOST to enable) ``` C'est un **avertissement, pas un échec**. Ton application peut envoyer des e-mails (vérification d'e-mail, réinitialisation de mot de passe, actions de notification) mais aucun serveur SMTP n'est configuré : l'e-mail est journalisé au lieu d'être envoyé — les liens d'inscription et de réinitialisation n'arriveront pas. Définis `SMTP_HOST` (et les variables `SMTP_*` associées) pour activer l'envoi. Voir [Variables d'environnement](/fr/docs/env-vars). ## MCP : « no token is set » ```text MCP env validation failed: MCP_AUTH_STRATEGY=token but no MCP_TOKEN_ADMIN/MEMBER/VIEWER is set. At least one role token must be configured for clients to authenticate. ``` Tu as activé le serveur MCP avec l'authentification par jeton mais sans définir de jeton. Fournis au moins un jeton de rôle (chacun doit faire 32 caractères ou plus) : ```bash MCP_TOKEN_ADMIN=$(openssl rand -hex 32) ``` Voir [Intégration MCP](/fr/docs/mcp-integration) pour la configuration complète de la connexion. ## Toujours bloqué ? - Lance `sovrium validate ` pour vérifier la configuration seule. - Un échec non rattrapé affiche `Unexpected error:` avec un message et un lien pour ouvrir un ticket — copie ce message dans ton rapport. - Cherche dans la documentation avec `⌘K`, ou ouvre un [ticket GitHub](https://github.com/sovrium/sovrium/issues) ou une [discussion](https://github.com/sovrium/sovrium/discussions). ## Pages liées - [Installation](/fr/docs/installation) — installation et premier lancement. - [Variables d'environnement](/fr/docs/env-vars) — chaque variable lue par Sovrium. - [Référence CLI](/fr/docs/cli) — commandes, options et sources de configuration. - [Fichiers de configuration](/fr/docs/configuration-files) — YAML, JSON et TypeScript.