Troubleshoot the Hub's built-in database

Memory too small, disk full, "la base intégrée n'a pas démarré": the console messages when the Hub's database, installed inside your panel server, has a problem, and the fix for each.

Updated on Oct 4, 2026, 5:45 p.m.

On this page

Before you start
Steps
You know it worked when…
If it does not work
Error messages (✗ line)
Warnings and normal lines
Going further
Where the database is, and what it exposes
Stopping and cutting
The panel's file copy is not a backup
Switching to an external PostgreSQL database (advanced option)
The numbers to remember

In short. When you install Agora through a panel egg, or on a Node.js server, the Hub provides its own PostgreSQL database inside your server: this is the "built-in database". It starts by itself. If it cannot, the panel's console says so in red (✗), with a line of advice (→). This page turns each message into a fix.

Before you start #

Check that you really use the built-in database. That is the case when the server's Base de donnees (DATABASE_URL) variable is empty, or, on a Node.js server, when agora.env has no DATABASE_URL line. If you filled in a PostgreSQL database yourself, this page is not about you: read The two Agora databases and the FAQ again.
Keep the panel's console open: everything is shown there.
The words (panel, console, PostgreSQL, quota) are in the glossary.

Steps #

Open the server's console in your panel and scroll up to the [5/6] Base de données — base intégrée, puis migrations step. This is where the database gets ready.
Look for the first red line. It starts with ✗; the next line, preceded by →, gives the advice. Orange lines with a ! are warnings: startup carries on.
Find the message in the table below and apply the fix.
Restart the server with Start. Startup resumes where it stopped: a database that already exists is never erased, and an interrupted start recovers by itself.

You know it worked when… #

The console shows ✓ base PostgreSQL intégrée prête, then ✓ schéma à jour, then ✓ Ready in ….
Your Hub's /api/health address answers "ok": true and "db": "ok".

If it does not work #

Error messages (`✗` line) #

Message in the console	What it means	What to do
`mémoire du serveur trop petite pour la base intégrée (… Mo)`	The server has less than 768 MB: Agora and its database do not fit	In the panel's administration, give the server 2 GB of memory (1.5 GB minimum), then restart
`pas assez de place sur le disque pour la base intégrée (… Mo libres, 400 Mo nécessaires)`	First start: the server's disk is too small	Raise the server's disk to 5 GB (10 GB is more comfortable), then restart
`plus de place sur le disque pour créer la base intégrée`	The disk filled up while the database was being created	Same fix: raise the disk, restart
`pas de base intégrée pour cette machine (…)`	The server is not a standard 64-bit Intel/AMD Linux (ARM, or an image without glibc)	The built-in database does not work here: pick another machine, or bring a PostgreSQL database (see below)
`téléchargement de PostgreSQL impossible : …`	The server cannot reach `registry.npmjs.org`	Check the server's Internet access (DNS, firewall), then restart. If it keeps happening, bring your own database
`installation de PostgreSQL impossible : …`	Extraction failed, often for lack of space	Free some space (400 MB free on the first start), then restart
`création de la base intégrée impossible (initdb)`	PostgreSQL could not initialise its files	Read the `Détail :` line right below; if it does not mention disk or memory, open a ticket with that line: see Open a support ticket
`création de la base « agora » impossible` or `mot de passe de la base intégrée non reposé`	A preparation step failed	Restart once. If it keeps happening, open a ticket with the `Détail :` line
`la base intégrée ne peut pas tourner en administrateur (root)`	The server runs Agora as `root`, which PostgreSQL refuses	On a panel it is normally an ordinary user: ask the panel administrator, or bring your own database
`dossier de données inadapté à la base intégrée (…)`	The data folder path is too long or contains unusual characters	Keep the default folders (`/home/container`); otherwise open a ticket
`la base intégrée n'a pas démarré`	PostgreSQL was launched but does not answer. The last lines of its log (`postgres.log`) follow	Most frequent cause: not enough memory or disk. Raise one or the other, restart; read the lines shown, they often name the cause
`la base de données n'a pas répondu`, in the migrations step	The database stopped on the way, or had no time to answer. The advice shown mentions `DATABASE_URL`: with the built-in database that is not the cause (the variable must stay empty)	Restart. If it comes back, look at memory (the panel may have stopped the process) and the `postgres.log` lines
`sauvegarde de la base impossible : les migrations n'ont PAS été appliquées`	The pre-migration backup could not be written (disk full)	Free or add space, then restart: the backup will be retried before migrating

Warnings and normal lines #

Message in the console	What it means	What to do
`! mémoire juste (… Mo) : avec la base intégrée, 1,5 Go sont un minimum et 2 Go sont recommandés`	The server starts, but with little margin: the panel may stop it	Move to 2 GB of memory
`! disque presque plein (… Mo libres) : la base risque de s'arrêter`	Less than 100 MB free	Free some space (old backups) or raise the disk
`première installation de la base intégrée (scram-sha-256, aucune écoute réseau)…`	Normal on the very first start	Nothing: the database is being created
`initialisation de la base interrompue au démarrage précédent : cluster vide effacé, on recommence`	The server was cut off during the very first creation of the database, which had held nothing yet	Nothing: it is redone
`verrou PostgreSQL orphelin (arrêt brutal) : retiré, la base rejouera son journal`	The server was cut off abruptly (Kill, memory, power cut)	Nothing: PostgreSQL recovers by itself
`mot de passe de la base intégrée introuvable : un nouveau est posé`	The password file was lost	Nothing: a new one is set, your data is kept
`la base intégrée ne tourne plus : redémarrage`	PostgreSQL stopped on the way (often for lack of memory); Agora relaunches it	Nothing if the `base de données redémarrée` line follows; otherwise check the server's memory

Going further #

Where the database is, and what it exposes #

Its data is in the server's .agora/pg folder (the data/pg folder on a Node.js server). It is the only folder that survives restarts.
It listens on no network port: it only talks to Agora through a local file. There is nothing to open in the firewall, and nothing is reachable from the Internet.
Its password is drawn once, stored in a locked file and never displayed.
Its log, postgres.log, is capped (about 5 MB). When la base intégrée n'a pas démarré appears, the console copies its last lines. The .agora folder is closed to the panel's file manager: do not expect to open it there, but those console lines are enough.

Stopping and cutting #

Stop lets Agora shut down first, then the database: you see arrêt demandé then base de données arrêtée proprement. Give it a few seconds.
Kill (or a power cut) is abrupt but harmless for the data: on the next start, PostgreSQL replays its journal by itself.

The panel's file copy is not a backup #

The server backup, the folder archive or a copy over SFTP copy the database while it is writing: the result is inconsistent, often unusable on restore. And the copy contains the database password. First make an Agora backup (an .sql file) and download it off the server: see Backups and restore.

Switching to an external PostgreSQL database (advanced option) #

Keep this for when the built-in database cannot run at your place. The principle: back up, change database, restore.

In Administration → Agora → Backups, create a backup and download the .sql file off the server.
Create your external PostgreSQL database (empty) and its user, at your database provider.
Paste its address (postgresql://user:password@host:5432/database?schema=public) in the Base de donnees variable, then restart. Agora starts on this empty database like a new installation.
Go through the setup if it shows up, then restore the .sql in Administration → Agora → Backups. Restoring is reserved for the installation's owner.
When everything works, the old .agora/pg folder is no longer used: you can delete it to free the space.

Setting DATABASE_URL does not touch the old folder: if you empty the variable again, you get back the old built-in database exactly as you left it. To go back from external to built-in, follow the same steps in reverse.

The numbers to remember #

	Value
Recommended memory	2 GB
Minimum memory	1.5 GB (under 768 MB, Agora refuses to launch the database)
Disk	5 GB; 400 MB free on the first start
Platform	64-bit Intel/AMD Linux with glibc (a panel's standard Node image)

Was this article helpful?