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 <config> : 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

[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 :

PORT=4000 sovrium start app.yaml

Un PORT hors limites est rejeté directement :

Error: Invalid port number "99999". Must be between 0 and 65535 (0 = auto-select).

« Server already running »

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 :

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 »

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.

« 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 :

Validation failed:
  <arbre indenté des erreurs précises>

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 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: <name> et se termine proprement.

« SOVRIUM_ENCRYPTION_KEY is required »

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 :

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.

« File not found » ou « No configuration provided »

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

Error: Failed to parse YAML file: app.yaml

Details: <l'erreur du parseur sous-jacent>

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 »

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 :

sovrium secret generate auth   # affiche AUTH_SECRET=<64-hex>

« Email sending disabled — SMTP not configured »

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.

MCP : « no token is set »

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) :

MCP_TOKEN_ADMIN=$(openssl rand -hex 32)

Voir Intégration MCP pour la configuration complète de la connexion.

Toujours bloqué ?

• Lance sovrium validate <config> 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 ou une discussion.

Pages liées

• Installation — installation et premier lancement.
• Variables d'environnement — chaque variable lue par Sovrium.
• Référence CLI — commandes, options et sources de configuration.
• Fichiers de configuration — YAML, JSON et TypeScript.