Dépannage

Docker n'est pas lancé

failed to connect to the docker API at unix:///…/docker.sock; check if the path is correct and if the daemon is running

Les anciennes versions de Docker affichent plutôt « Cannot connect to the Docker daemon ». Dans les deux cas, le moteur Docker n'est pas démarré.

1. 01

   Ouvrez Docker Desktop

   Lancez Docker Desktop et attendez qu'il indique que le moteur est en marche. Sous Linux, démarrez le service : sudo systemctl start docker.
2. 02

   Vérifiez que Docker répond

   TerminalCopier

   docker info

   Résultat attendu: Une section Server s'affiche au lieu d'une erreur.
3. 03

   Relancez votre commande de démarrage

   docker compose up --build pour le pack Full Stack, ou vos commandes docker build et docker run pour une application seule.

Un port est déjà utilisé

ports are not available: exposing port TCP 0.0.0.0:3031 … bind: address already in use
Bind for 0.0.0.0:3031 failed: port is already allocated
Error: listen EADDRINUSE: address already in use :::3031

Les deux premières lignes viennent de Docker, la dernière de yarn dev. Un autre programme écoute déjà sur 3030, 3031 ou 8000 : souvent un lancement précédent de Northstack, ou le serveur de développement d'un autre projet.

1. 01

   Trouvez ce qui occupe le port

   Sous macOS ou Linux, avec le port indiqué dans le message :

   TerminalCopier

   lsof -i :3031

   Sous Windows, dans PowerShell :

   TerminalCopier

   netstat -ano | findstr :3031
2. 02

   Arrêtez-le

   Fermez ce programme, ou arrêtez le lancement précédent : Ctrl+C dans son terminal, docker compose down dans son dossier, ou docker stop pour un conteneur démarré avec docker run. Puis redémarrez Northstack.
3. 03

   Ou lancer Northstack sur d'autres ports

   Avec le full stack dans Docker, créez un fichier nommé .env dans le dossier northstack-full-stack, à côté de docker-compose.yml, avec le port voulu. SITE_PORT déplace le site, ADMIN_PORT le tableau de bord et API_PORT l'API ; les adresses que les applications utilisent, CORS_ORIGIN compris, suivent d'elles-mêmes.

   northstack-full-stack/.envCopier

   ADMIN_PORT=3041

   Puis relancez la même commande. Un démarrage échoué reprend là où il s'est arrêté. Docker nomme un seul port occupé à la fois : s'il s'arrête sur un autre, ajoutez-le aussi au .env.

   Terminaldans northstack-full-stackCopier

   docker compose up --build

   Résultat attendu: L'application répond sur son nouveau port, ici localhost:3041Local.

Le build Docker échoue

Le premier build télécharge les images de base et toutes les dépendances, puis construit les images. Quand quelque chose bloque, il s'arrête avec « failed to solve » et l'étape qui a échoué.

• Pas de connexion ou délai dépassé : le build a besoin d'un accès à internet. Relancez la commande une fois en ligne ; les étapes terminées sont en cache.
• No space left on device : libérez de l'espace dans Docker Desktop, ou vérifiez ce que Docker occupe avec docker system df.
• L'échec survient toujours à la même étape : reconstruisez sans le cache, puis démarrez.
• Compose rejette `docker-compose.yml` lui-même, en citant `env_file` : votre Compose est antérieur à 2.24. Mettez à jour Docker Desktop, ou le plugin Compose sous Linux.

docker compose build --no-cache
docker compose up

Pour un pack à application unique, ajoutez --no-cache à votre commande docker build.

Un premier démarrage qui semble bloqué est généralement en train d'initialiser les espaces de travail d'exemple et les 732 organisations derrière les chiffres de la plateforme. Le site et le tableau de bord ne démarrent qu'une fois l'API déclarée en bonne santé.

Yarn indique la version 1.22

This project's package.json defines "packageManager": "yarn@4…". However the current global version of Yarn is 1.22…

Chaque application fixe Yarn 4.8.1 via Corepack. Ce message signifie que Corepack n'est pas encore activé, et c'est donc l'ancien Yarn global qui a répondu.

corepack enable

Puis relancez yarn install. Si votre Node.js n'a pas Corepack (Node.js 25 et plus récent ne l'inclut plus), installez-le d'abord avec npm install -g corepack. npm et pnpm ne sont pas utilisés : chaque application livre son propre yarn.lock.

Une installation ou un démarrage échoue avec une version ancienne de Node.js

L'API demande Node.js 22.13 ou une version 22 plus récente, ou Node.js 24.11 ou plus ; le site et le tableau de bord seuls demandent Node.js 22.9 ou plus. Les images Docker utilisent Node.js 24. Un Node.js trop ancien se manifeste par une installation qui n'arrive pas à construire un paquet, ou par une application qui s'arrête au démarrage.

node -v

S'il affiche une version plus ancienne, installez Node.js 24 (ou une version 22 à partir de 22.13), relancez corepack enable (sur Node.js 25 et plus, npm install -g corepack d'abord), puis supprimez le dossier node_modules de l'application et relancez yarn install. Node.js 23, et les versions 24 antérieures à 24.11, sont aussi hors de la plage de l'API. Avec Docker, rien de cela ne s'applique : les images apportent leur propre Node.js.

L'API s'arrête avant de démarrer

The API cannot start: JWT_SECRET is not set. Set it in back-end/.env to the output of: …
The API cannot start: JWT_SECRET is still the example value from .env.example, so anyone can sign a token for any account. …
The API cannot start: CORS_ORIGIN is not set. List the website and dashboard origins, comma separated, …

L'API vérifie ses paramètres avant de démarrer et affiche une ligne par problème. Les causes :

• Il n'y a pas de fichier `.env`, ou `JWT_SECRET` est vide. Créez le fichier dans le dossier de l'API avec cp .env.example .env.
• `JWT_SECRET` a encore la valeur d'exemple avec `NODE_ENV=production`. N'importe qui pourrait signer un jeton avec l'exemple public : un démarrage en production le refuse donc. Générez votre propre secret.
• `CORS_ORIGIN` est vide avec `NODE_ENV=production`. Indiquez l'adresse du site et celle du tableau de bord, séparées par une virgule.

Générez un secret avec :

node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"

Avec Docker, vous n'en avez pas besoin : un conteneur sans JWT_SECRET propre, ou avec celui de l'exemple, génère un secret et le conserve dans le volume de données.

• Paramètres essentiels de l'API

Personne ne peut se connecter sur une nouvelle base

Sans Docker, yarn dev avec NODE_ENV=development crée les tables à son premier démarrage, mais aucun compte : les comptes et les espaces de travail d'exemple viennent de yarn seed. Arrêtez l'API, lancez-le dans le dossier de l'API, puis redémarrez l'API.

yarn seed
yarn dev

Il se termine par Seed complete. et les comptes à utiliser pour se connecter. En cas d'échec, il affiche Seeding failed: suivi de la raison, par exemple une base MySQL qui n'existe pas encore. L'image Docker initialise seule un nouveau volume SQLite ; sur MySQL, lancez une fois node dist/database/seeder.js dans le conteneur.

Une base démarrée à vide (yarn schema, ou Docker avec SEED_SAMPLE_DATA=false sans ADMIN_EMAIL ni ADMIN_PASSWORD) n'a pas non plus de compte, volontairement. Créez votre premier admin de la plateforme avec yarn admin:create (compilé : yarn admin:create:prod ; Docker : docker compose exec -u node api node dist/database/create-admin.js), qui demande l'e-mail et les identifiants de connexion.

La connexion échoue

That email and password do not match an account. Try again.
Too many failed sign-in attempts. Wait 15 minutes, then try again.

• Vérifiez le compte. Chaque compte se connecte sur le tableau de bord, au port 3031 ; le site n'a pas de connexion propre, et ses boutons Live demo ouvrent la connexion du tableau de bord. Les comptes du seed et leur mot de passe sont sur la page d'installation.
• Le même message répond à un mauvais mot de passe, à un e-mail inconnu et à une base jamais initialisée. Vérifiez ce que vous avez saisi ; sur une nouvelle base, yarn seed dans le dossier de l'API crée les comptes.
• « Too many failed sign-in attempts. Wait 15 minutes, then try again. » Dix connexions échouées depuis une même adresse en 15 minutes refusent chaque nouvel essai depuis celle-ci, même avec le bon mot de passe, jusqu'à ce que le plus ancien échec ait 15 minutes. Patientez, ou redémarrez l'API : le compte est gardé dans sa mémoire. RATE_LIMIT_LOGIN dans le .env de l'API change le nombre.
• « New sign-ups are closed on this platform right now. » sur la page d'inscription ou dans l'onboarding : le personnel de la plateforme a désactivé New sign-ups dans les paramètres de la plateforme. Les comptes existants se connectent toujours.
• Vous avez changé un mot de passe et vous ne l'avez plus : repartez de données de démonstration neuves, plus bas.
• Connecté, mais la page affiche l'avis Sample data : le tableau de bord n'a pas pu joindre son API et a répondu depuis ses données d'exemple. Voir le problème suivant.

• Les comptes du seed

La connexion échoue

• Vérifiez le compte et la route. Chaque compte se connecte sur POST /api/auth/login ; les comptes du seed et leur mot de passe sont sur la page d'installation. Une connexion échouée répond 401 avec le même message, que l'e-mail ou le mot de passe soit faux.
• Aucun compte ne fonctionne : la base a été créée sans les données d'exemple. Lancez yarn seed pour les comptes d'exemple, ou yarn admin:create pour votre propre admin de la plateforme, comme dans le problème ci-dessus.
• Une réponse `429` signifie qu'une adresse a échoué 10 connexions en 15 minutes. Elle disparaît quand le plus ancien échec a 15 minutes, ou au redémarrage de l'API. RATE_LIMIT_LOGIN change ce nombre.

• Les comptes du seed

Un avis Sample data est affiché en bas de chaque page

No API is connected, so this dashboard runs on built-in sample data and your changes stay in this browser. …
The API at http://localhost:8000/api is not answering, so this dashboard is showing built-in sample data, not your workspace's. …

Le site le dit avec ses propres mots. Chaque frontend embarque des données d'exemple et répond depuis elles dans deux cas :

• « No API is connected » : l'application a été démarrée ou construite avec NEXT_PUBLIC_API_BASE_URL vide, ou sans aucun .env. C'est ainsi qu'un pack de frontend seul fonctionne. Pour utiliser une API, définissez-la dans .env avec l'adresse de l'API et /api (http://localhost:8000/api, comme dans .env.example), puis redémarrez yarn dev ou reconstruisez ; avec Docker, construisez sans --build-arg NEXT_PUBLIC_API_BASE_URL=.
• « The API at … is not answering » : une adresse est définie, mais le navigateur ne peut pas l'atteindre. L'API n'est pas lancée, tourne à une autre adresse, ou ne liste pas l'adresse de cette application dans son CORS_ORIGIN (voir le problème suivant). Vérifiez que localhost:8000/api/healthLocal répond, puis rechargez la page. L'application réessaie l'API d'elle-même.

Tant que les données d'exemple prennent le relais, ce que vous modifiez reste dans ce navigateur seulement, et dans le tableau de bord n'importe quel mot de passe permet de se connecter. Entre-temps, le navigateur continue d'essayer l'adresse et consigne chaque requête refusée dans sa console : laissez donc l'adresse vide quand il n'y a pas d'API. Le site affiche l'avis avec yarn dev, et dans un build de production seulement s'il a été construit avec NEXT_PUBLIC_SAMPLE_DATA_NOTICE=always (--build-arg NEXT_PUBLIC_SAMPLE_DATA_NOTICE=always avec Docker) ; les pages que son serveur rend n'utilisent jamais ce repli.

• Les données d'exemple

Le navigateur affiche « blocked by CORS policy »

Access to XMLHttpRequest at 'http://localhost:8000/api/…' from origin 'http://localhost:3041' has been blocked by CORS policy

La console du navigateur affiche cette ligne quand un frontend tourne à une adresse que l'API n'accepte pas. Une requête refusée compte comme une API qui ne répond pas : le frontend prend alors le relais avec ses données d'exemple dans le navigateur. Le tableau de bord affiche l'avis Sample data, et le site aussi avec yarn dev. L'API ne répond aux navigateurs que depuis les adresses de CORS_ORIGIN, qui vaut par défaut http://localhost:3030 et http://localhost:3031. Un site ou un tableau de bord déplacé sur un autre port, ou servi sur votre propre domaine, est refusé tant qu'il n'est pas listé.

CORS_ORIGIN=http://localhost:3030,http://localhost:3041
FRONTEND_URL=http://localhost:3041
DASHBOARD_URL=http://localhost:3041

• Écrivez chaque adresse exactement comme le navigateur l'affiche, avec le schéma et le port et sans barre oblique finale, séparées par des virgules. Puis redémarrez l'API.
• FRONTEND_URL est l'adresse du tableau de bord, depuis laquelle se connectent ses mises à jour de permissions en direct, et DASHBOARD_URL celle qui est écrite dans les liens d'invitation et de réinitialisation. Déplacez les deux avec le tableau de bord ; déplacez WEBSITE_URL avec le site.
• Pour un conteneur de l'API, passez les mêmes valeurs avec -e, par exemple -e CORS_ORIGIN=http://localhost:3030,http://localhost:3041.
• Avec le pack complet sous Docker, vous ne les modifiez pas : SITE_PORT, ADMIN_PORT, SITE_URL et ADMIN_URL dans le .env à côté de docker-compose.yml les définissent.
• Un frontend qui ne peut pas joindre l'API du tout, parce qu'elle est arrêtée ou à une autre adresse, échoue de la même façon, sans la ligne CORS. Vérifiez que localhost:8000/api/healthLocal répond, et que le NEXT_PUBLIC_API_BASE_URL du frontend désigne bien cette API.

• Déployer

Le reçu du paiement se charge tard dans Docker

Le serveur du site lit lui-même les options du paiement et le reçu d'une commande quand il rend ces pages. Dans un conteneur, localhost désigne le conteneur lui-même : ce serveur ne peut donc pas joindre une API sur votre ordinateur à http://localhost:8000. Les pages se terminent quand même dans le navigateur, qui atteint l'API directement.

Démarrez le conteneur du site avec l'adresse de l'API telle que le serveur la voit :

docker run -p 3030:3030 -e API_INTERNAL_URL=http://host.docker.internal:8000/api --add-host=host.docker.internal:host-gateway northstack-website

La pile complète dans Docker la définit pour vous (http://api:8000/api). Sans Docker, ce n'est pas nécessaire.

Une invitation ou un e-mail de réinitialisation n'arrive jamais

Tant que SMTP_HOST n'est pas défini dans le .env de l'API, aucun e-mail n'est envoyé. L'API le signale au démarrage, et chaque message (invitations, résumés hebdomadaires, réinitialisations de mot de passe, reçus de licence, e-mails de facturation et messages de contact transférés) est écrit dans son journal à la place, liens compris :

Mail is not set up (SMTP_HOST is empty): invitations, weekly digests, billing emails, password resets, licence receipts and forwarded contact messages are written to this log instead of being sent.
Message to …: …

• Full stack dans Docker : lancez docker compose logs api dans le dossier du pack et ouvrez le lien du message le plus récent.
• Sans Docker : lisez-le dans le terminal qui exécute le yarn dev de l'API.
• Conteneur d'API : docker logs avec l'identifiant du conteneur (docker ps le liste).
• Pour envoyer de vrais e-mails, définissez SMTP_HOST et les autres valeurs SMTP_*, puis redémarrez l'API. Un message que le serveur refuse est consigné avec Could not send et la raison.
• Une invitation dure sept jours ; ensuite sa page indique « This invitation has expired. » Envoyez-en une nouvelle depuis la page Team.
• Aucun e-mail de facturation n'arrive (un paiement échoué, un essai terminé, un changement de formule) : ils vont uniquement au propriétaire de l'espace de travail, à ses membres de facturation et à son adresse de facturation, et seulement tant que Email notifications est activé dans Settings, Notifications de l'espace.
• Pas encore de résumé hebdomadaire : il part le lundi à partir de 08:00 UTC, tant que Weekly digest est activé. Le premier passage d'une nouvelle installation marque seulement la semaine en cours, et le premier résumé d'un nouvel espace de travail couvre sa première semaine complète.

• Paramètres des e-mails

Un paiement ouvre le paiement test

Les deux parcours de paiement ouvrent un paiement test intégré tant que l'API n'a pas de clés pour eux, et aucun ne débite personne :

• Change plan dans la page Billing du tableau de bord ouvre la page Test checkout, « Confirm the … plan », jusqu'à ce que STRIPE_SECRET_KEY soit défini (ou toujours, avec BILLING_PROVIDER=simulator). Manage payment method indique alors « The test checkout keeps no card, so there is no payment method to manage. »
• Le paiement des licences du site affiche « Test mode: payments go through this site's test checkout and charge nobody. » et ouvre sa propre page Test checkout. La carte utilise Stripe dès que STRIPE_SECRET_KEY est défini, et PayPal dès que PAYPAL_CLIENT_ID et PAYPAL_CLIENT_SECRET le sont.
• Une clé de test Stripe affiche « Test mode: no real money moves. » Sur la page de Stripe, payez avec la carte 4242 4242 4242 4242, n'importe quelle date future et n'importe quel CVC.
• « Confirming the payment... » ou un reçu qui indique que le paiement est encore en cours de confirmation : l'API interroge Stripe sur la session pendant que la page attend, et sur un serveur le webhook sur /api/billing/webhooks/stripe la confirme aussitôt. Une formule ne change qu'une fois le paiement confirmé.
• « The checkout expired. Start again from Change plan. » Une session de paiement restée ouverte trop longtemps ; démarrez-en une nouvelle.
• Les paiements Stripe passent mais les renouvellements, les paiements échoués ou les annulations n'apparaissent jamais sur un serveur : STRIPE_WEBHOOK_SECRET est vide ou faux. Le journal de l'API indique STRIPE_WEBHOOK_SECRET is empty au démarrage, et le dashboard de Stripe montre chaque envoi refusé avec un 400. Définissez-le avec le secret de signature du point de terminaison webhook et redémarrez l'API.

• Paramètres de paiement

Erreurs après une mise à jour

Après avoir mis à jour le code sur une base que vous conservez, des requêtes peuvent échouer avec une table ou une colonne manquante dans le journal de l'API, comme no such column sur SQLite ou Unknown column sur MySQL. Il n'y a pas de migrations, et en production l'API ne modifie jamais les tables seule : mettez-les donc au niveau du nouveau code une fois. Sauvegardez d'abord la base : la mise à jour supprime aussi une colonne que le code n'a plus.

yarn build
yarn schema:prod

Avec Docker, lancez-le dans le conteneur de l'API en cours d'exécution : docker compose exec -u node api node dist/database/schema.js.

• Mise à jour

Tout le monde voit « Closed for maintenance. »

Le paramètre de plateforme Maintenance mode est activé. Tant qu'il ne l'est pas désactivé, seul le personnel de la plateforme peut utiliser le tableau de bord et l'API répond 503 à tous les autres. Sur l'écran de maintenance, appuyez sur Platform staff sign in, connectez-vous comme admin de la plateforme et désactivez maintenance_mode dans la page Settings de la plateforme. Le formulaire de contact et le paiement des licences du site continuent de fonctionner entre-temps.

• Paramètres de la plateforme

Une modification du .env d'un frontend n'a aucun effet

Chaque valeur NEXT_PUBLIC_* du .env du site et du tableau de bord est compilée dans le JavaScript que charge le navigateur quand l'application est construite : modifier le fichier ne change donc rien tant que l'application n'est pas reconstruite.

• Avec `yarn dev` : arrêtez-le et relancez yarn dev.
• Avec `yarn build` et `yarn start` : relancez yarn build.
• Avec Docker Compose : mettez la valeur dans le .env à côté de docker-compose.yml (les ports et SITE_URL, ADMIN_URL, API_URL), pas dans le dossier de l'application, et lancez docker compose up --build.
• Pour l'image d'une application seule : reconstruisez-la avec la valeur en --build-arg.

Le .env de l'API n'a besoin que d'un redémarrage. Le PORT du tableau de bord et l'API_INTERNAL_URL du site sont lus au démarrage de l'application.

L'assistant demande une clé, ou un fournisseur refuse

Use your own API key
The server has no key for this provider. Add your own and the assistant works fully. …

L'assistant répond avec Google Gemini, OpenAI ou DeepSeek, et le .env de l'API n'a aucune clé de fournisseur tant que vous n'en ajoutez pas, donc rien n'est facturé. L'API le signale au démarrage (No AI provider key is set), et l'envoi d'un message ouvre Use your own API key. Ajoutez-y votre propre clé, qui reste dans votre navigateur et ne sert qu'à vos requêtes, ou donnez-en une au serveur :

• Ajoutez GOOGLE_API_KEY, OPENAI_API_KEY ou DEEPSEEK_API_KEY au .env de l'API et redémarrez l'API.
• Avec Docker Compose, copiez d'abord back-end/.env.example vers back-end/.env, ajoutez la clé, puis relancez docker compose up --build.
• La clé propre d'un lecteur est utilisée avant celle du serveur : un lecteur qui en a ajouté une est donc facturé dessus même quand le serveur a une clé.

… has no requests left on this API key right now. Pick a different model from the list above the chat, or try again in a few minutes.

Cette réponse signifie que le fournisseur a refusé à cause de ses propres limites. Choisissez un autre modèle dans le sélecteur, ou patientez et appuyez sur Try again. Tout autre refus, comme une clé que le fournisseur n'a pas acceptée, affiche le message du fournisseur lui-même. Sur les seules données d'exemple, l'assistant ne répond pas du tout : il indique qu'il a besoin de l'API.

• L'assistant IA

En mode démo, l'assistant demande la clé propre du visiteur

Le formulaire de contact ou le paiement demande de réessayer plus tard

You have sent several messages in the last hour. Try again later.
Too many attempts from this address. Try again in an hour.

Chaque adresse peut envoyer cinq messages de contact et démarrer dix paiements de licence par heure ; l'inscription du tableau de bord en autorise dix par heure, et les demandes de réinitialisation de mot de passe cinq par 15 minutes. La réponse 429 de l'API nomme l'action et l'attente, par exemple « Too many sign-ups from this address. Wait an hour, then try again. » Patientez, ou redémarrez l'API pendant vos tests, car les compteurs vivent dans sa mémoire. Derrière un reverse proxy, définissez TRUST_PROXY=1 dans le .env de l'API, sinon tous les visiteurs partagent le seul quota du proxy ; il en va de même pour la limite de connexion.

MySQL refuse d'initialiser

yarn seed avec DB_TYPE=mysql crée les tables dans une base qui existe déjà ; il ne crée pas la base elle-même. Seeding failed: suivi de Unknown database signifie qu'elle manque, et Access denied que DB_USERNAME ou DB_PASSWORD est faux.

mysql -u root -p -e "CREATE DATABASE northstack"

Puis relancez yarn seed. L'image Docker n'initialise que SQLite : avec MySQL, lancez node dist/database/seeder.js (ou node dist/database/create-admin.js pour partir à vide) une fois dans le conteneur de l'API avec le même environnement.

• Utiliser MySQL à la place

La commande unzip échoue ou le dossier est différent

caution: filename not matched:  …zip

Cela signifie que deux ZIP du même pack se trouvent dans le dossier, par exemple un ancien téléchargement à côté du nouveau, et que le * de unzip -q northstack-full-stack-*.zip les a trouvés tous les deux. Supprimez l'ancien ZIP et relancez la commande, ou tapez le nom de fichier complet.

• Si unzip est absent, extrayez le ZIP dans votre gestionnaire de fichiers. Certains outils ajoutent un dossier supplémentaire portant le nom du ZIP : placez-vous dans celui de l'intérieur.
• Le Full Stack s'extrait dans northstack-full-stack, avec back-end, dashboard, website et docker-compose.yml.
• Les applications seules s'extraient dans northstack-website, northstack-dashboard et northstack-backend, chacune avec son propre Dockerfile.

Repartir de données de démonstration neuves

Avec le full stack dans Docker, dans le dossier northstack-full-stack :

docker compose down -v
docker compose up

Avec le seul conteneur de l'API, supprimez le conteneur (docker rm -f avec son nom), puis le volume, et relancez-le :

docker volume rm northstack-api-data
docker run -p 8000:8000 -v northstack-api-data:/data northstack-api

Sans Docker, arrêtez l'API et lancez ceci dans son dossier (dans PowerShell, Remove-Item database.sqlite*; yarn seed) :

rm -f database.sqlite* && yarn seed

Sur MySQL, lancez yarn reset (il vide chaque table), puis yarn seed.

Lancer yarn seed sur une base que vous conservez n'est pas une réinitialisation : dès que la base a des comptes, il n'ajoute ni compte ni espace de travail et redonne seulement leurs permissions aux rôles intégrés de la plateforme.