Skip to content
You're viewing documentation for v2026.11.12-beta. It may be out of date.Go to latest
TimescaleDB Enterprise
Esc
↑↓navigate↵open⌘Jpreview
On this page

Disk full on the primary

Stop writes, free space with a balloon file or a larger disk, and confirm the recovery when the data disk of the primary of a service is full.

What happens

The disk that holds the PostgreSQL data directory of the primary is full. Writes fail, and PostgreSQL can stop. Common causes: data growth, an inactive replication slot that keeps WAL, large temporary files, and logs.

Symptoms

  • Writes fail with ERROR: could not extend file "base/...": No space left on device (SQLSTATE 53100, disk_full). Reads can continue.
  • When a WAL write fails, PostgreSQL stops. Patroni restarts it, and each restart fails until there is free space. Connections drop at each restart. On an HA service, Patroni can fail over.
  • In the topology on the service Overview, the member shows start failed or crashed, and the Patroni health is unhealthy. While PostgreSQL is up, the health can stay healthy.
  • The Storage panel on the Monitoring tab shows the disk full or almost full.
  • When etcd uses the same disk, the etcd health shows the member on the primary as unhealthy. A Standard service has one etcd member, so it can lose quorum.

Triage

Find what uses the space before you choose a lasting fix. To find the disk of the data directory, see Grow storage on a server.

Cause Do this
The database needs more space Grow the storage. Then go to step 3 of the recovery. On an HA service, also check each replica.
Retained WAL, logs, temporary files or other files Do the recovery steps.
You need space now, or the cause is not known Do the recovery steps. A balloon file gives time. It does not remove the cause.

Do not delete PostgreSQL data or WAL files by hand.

Recovery

Stop the applications

Stop the applications that write to the database. Keep them stopped until step 5.

Free space on the primary

Free space on the full primary, even if another server is now the leader. Use one of these methods:

If you cannot free space or grow the disk, contact support.

Wait for the server

Wait for the server to recover. In the topology on the service Overview, the server must show a healthy status dot and no state label such as start failed. A replica must show a lag near 0. If the console cannot reach the cluster, use step 1 of Return to service. If the server does not recover, keep the applications stopped and contact support.

Leave the new leader

If Patroni failed over, the old primary rejoins as a replica. Do not force it back to leader. A switchover is optional.

Allow writes again

  • Console: make sure that the Database service is read-only. banner shows, then click Return to service. If the banner is missing or the action fails, keep the applications stopped and contact support.
  • By hand: do Return to service.
  • Grown storage only: nothing to do. The setting did not change.

Run one safe test write on the leader, then start the applications. If the write fails, keep them stopped and contact support.

Restore the reserve

Return to service starts a run on the Operations tab that recreates it. If you deleted a file by hand, choose Recreate emergency reserve in the server menu. See Recreate the balloon.

Check the free space

Check the free space on the primary and on each replica. Grow each disk that needs more space.

Prevention

  • Configure alert delivery. The built-in disk rules warn at 80% used and are critical at 90% used.
  • Keep the balloon files in place.
  • Put the data directory on its own disk with Storage locations when you create a service. Then etcd and the system journal do not use the database disk.
  • Drop replication slots that no consumer uses. Each slot keeps WAL on the primary.