coollabsio/coolify · error · RuntimeException

The storage backup archive is empty or was not created.

Error message

The storage backup archive is empty or was not created.

What it means

VolumeBackupJob archives a Docker volume on the server, then verifies the result by running `du -b <backupLocation>` over SSH and reading the byte size. If the size is 0 or the command yields nothing, the archive never materialized and this RuntimeException aborts the run before S3 upload, retention cleanup, or container recovery proceed.

Source

Thrown at app/Jobs/VolumeBackupJob.php:124

            instant_remote_process([
                $verifySourceCommand,
                'mkdir -p '.escapeshellarg($backupDirectory),
                $archiveCommand,
            ], $server, timeout: $this->timeout, disableMultiplexing: true);
            $this->execution->update([
                'stop_container_ids' => null,
                'stop_recovery_pending' => false,
            ]);

            $size = (int) instant_remote_process(
                ['du -b '.escapeshellarg($backupLocation).' | cut -f1'],
                $server,
                disableMultiplexing: true,
            );

            if ($size <= 0) {
                throw new \RuntimeException('The storage backup archive is empty or was not created.');
            }

            $warning = null;
            $s3Uploaded = null;
            $s3CleanupPending = false;
            $localStorageDeleted = false;

            if ($this->backup->save_s3) {
                $s3CleanupPending = true;
                $this->execution->update(['s3_cleanup_pending' => true]);

                try {
                    $this->uploadToS3($backupLocation, $backupDirectory, $server);
                    $s3Uploaded = true;
                    $s3CleanupPending = false;
                } catch (Throwable $exception) {
                    $s3Uploaded = false;
                    $warning = 'S3 upload failed: '.$exception->getMessage();

View on GitHub (pinned to 70b9acc424)

Solutions

1. SSH to the server and check free space (`df -h`) and the backup staging directory contents
2. Re-run the backup from the UI and read the execution log for the underlying tar command and its exit status
3. Verify the volume exists and holds data: `docker run --rm -v <volume>:/data alpine du -sb /data`
4. Check write permissions on the backup directory for the user Coolify connects as

// pre-flight: confirm disk space on the server before the backup window
$freeBytes = (int) instant_remote_process(['df -B1 --output=avail / | tail -1'], $server);
if ($freeBytes < $estimatedArchiveBytes) {
    // alert and skip instead of producing a 0-byte archive
}

Catch \RuntimeException around the backup execution, mark the execution failed, and persist the message on the execution row so the UI shows why the archive was rejected before any S3 upload or container stop.

When it happens

Trigger: The backup command completed without creating the file at backupLocation, or created a zero-byte archive: tar failed silently, the volume is empty or not mounted at the expected path, the staging path is wrong, or the disk filled mid-write.

Common situations: Empty or externally-managed volumes; servers out of disk space; wrong or stale backup directory setting; permissions blocking the SSH user from writing the staging path; another process (tmp cleaner, backup janitor) deleting the file between creation and the size check.

Related errors

• The selected S3 storage no longer exists. S3 backup has been
• The server is unavailable for container recovery.
• Invalid Cron / Human expression
• Private key not found. Please add a private key to the appli
• Command execution failed (exit code {$process_result->exitCo

AI-assisted analysis of coollabsio/coolify@70b9acc424 (2026-08-17). Data as JSON: /api/errors/51d55f7538256aa5. Report an issue: GitHub.