Dépannage : démarrage et configuration

Les erreurs que tu risques le plus de rencontrer entre le moment où tu tapes sovrium start et celui où une URL s'affiche. Chaque entrée cite le message réel, pour que tu puisses le retrouver dans ton terminal.

Bloqué sur une configuration ? Lance d'abord sovrium validate <config> : la commande vérifie le fichier seul et n'exige rien d'autre en fonctionnement.

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 le port : Sovrium en prend un libre au lieu d'échouer. Lis l'URL dans la bannière de démarrage, ou choisis toi-même un port :

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 tourne déjà — Sovrium la suit avec un fichier de verrou. Arrête-la avec sovrium stop.

Un verrou laissé par un processus planté (son PID a disparu) 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 vaut quelque chose de non reconnu — un simple chemin de fichier est l'erreur classique. Trois bonnes réponses :

• Laisse DATABASE_URL vide. Sovrium utilise une base SQLite embarquée, sans serveur à installer.
• Pointe vers un fichier SQLite avec le préfixe file: — file:./database.db.
• Utilise PostgreSQL avec une URL complète — postgres://user:password@localhost:5432/app.

« Sovrium refused this configuration » / « Error: Validation failed. »

Chaque démarrage — et chaque sovrium validate et sovrium build — décode ta configuration face au même schéma. validate affiche le constat sous Error: Validation failed. ; start et build affichent le même constat sous une ligne qui nomme ce qui n'a pas eu lieu :

Error: Sovrium refused this configuration — nothing was started.

  Unknown property 'tag' on component type 'text'
    at pages[0].components[0]
    Accepted here: type, children, props, content, ..., element, required

La propriété que tu as écrite n'est pas déclarée par le schéma à cet endroit. Compare-la à la liste des clés acceptées, ou déplace-la sous props s'il s'agit d'un attribut HTML/ARIA brut — props est transmis au navigateur sans interprétation.

Les problèmes structurels qui ne sont pas une clé parasite (un name manquant, un nombre là où une chaîne est attendue) s'affichent toujours en arbre indenté, celui du décodeur. Lis-le par le bas : le haut est de la mécanique de schéma, et les dernières lignes nomment la propriété et la raison (is missing, is unexpected, expected: ...).

Guide complet sur Valider une configuration.

« Sovrium could not write its encryption key »

Sovrium failed to start: Sovrium could not write its encryption key to
/srv/app/.sovrium/encryption-key (EACCES: permission denied). Point
SOVRIUM_DATA_DIR at a writable directory, or set SOVRIUM_ENCRYPTION_KEY so no
key needs to be written.

Une SOVRIUM_ENCRYPTION_KEY absente n'est pas une erreur — Sovrium génère une clé au premier démarrage et la conserve dans le répertoire de données. Voici le seul cas où il n'y arrive pas : le répertoire est en lecture seule, appartient à un autre utilisateur, ou un fichier occupe la place attendue pour un dossier. Le message nomme le chemin exact qu'il a essayé. Les deux corrections fonctionnent :

SOVRIUM_DATA_DIR=/var/lib/sovrium   # un répertoire inscriptible par le processus, ou
SOVRIUM_ENCRYPTION_KEY=<64-hex>     # fournis la clé, et rien n'est écrit

Sovrium refuse de démarrer plutôt que de se rabattre sur une clé gardée en mémoire seulement. Une telle clé tient jusqu'au redémarrage suivant, puis laisse derrière elle des identifiants stockés que plus rien ne peut déchiffrer — une panne qui remonte des jours plus tard, dans l'intégration de quelqu'un d'autre.

« File not found » ou « No configuration provided »

Error: File not found: app.yaml

Le chemin n'existe pas — vérifie le nom et le dossier. Deux voisines :

• Error: No configuration provided — aucun chemin de configuration et pas d'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. La cause classique : des tabulations dans un fichier YAML — l'indentation doit utiliser des espaces. Lis la ligne Details: pour la position, corrige, puis relance sovrium validate app.yaml. Les configurations TypeScript affichent plutôt Failed to load TypeScript file, c'est-à-dire une erreur de type ou d'import.

Auth : « JWT signing keys could not be read »

Déplacé vers Dépannage : authentification, e-mail et MCP.

« Email sending disabled — SMTP not configured »

Déplacé vers Dépannage : authentification, e-mail et MCP.

MCP : « no token is set »

Déplacé vers Dépannage : authentification, e-mail et MCP.

Toujours bloqué ?

Voir la section « Toujours bloqué ? » de Dépannage : authentification, e-mail et MCP.

Pages liées

• Installation — installation et premier lancement.
• Variables d'environnement — chaque variable lue par Sovrium.
• Commandes de cycle de vie — start, stop et le fichier de verrou.
• Valider une configuration — lire un arbre de validation.