# Detecting When Laravel backup:clean Fails to Run

> Find out when php artisan backup:clean silently skips cleanup and old backups start filling your disk. Get alerted before storage costs spiral.

Source: https://crontinel.com/use-cases/monitor-backup-clean/

Your S3 bill arrives. It's 40% higher than last month. You dig into CloudWatch and find 180 backup archives sitting in your S3 bucket, dating back 6 months. `backup:run` has been executing flawlessly every night. `backup:clean` has been failing silently for months. You now have 180 daily backups worth of data sitting in cold storage, generating costs you didn't budget for.

The problem with backup monitoring is that most tools watch for the backup to run. Nobody watches for the cleanup to work.

## How backup:clean Works

The `spatie/laravel-backup` cleanup process runs separately from `backup:run`. It reads your `backup.php` retention configuration and deletes archives older than your specified thresholds:

```php
// config/backup.php
'cleanup' => [
    'strategy' => \Spatie\Backup\Tasks\Cleanup\Strategies\DefaultStrategy::class,
    'default_strategy' => [
        'keep_all_backups_for_days' => 7,
        'keep_daily_backups_for_days' => 16,
        'keep_weekly_backups_for_months' => 1,
        'keep_monthly_backups_for_year' => 1,
        'keep_yearly_backups_for_years' => 1,
        'delete_oldest_backups_when_using_more_energy_than' => 5000,
    ],
],
```

When `backup:clean` runs, it evaluates all existing backups against this policy and deletes anything that falls outside the retention window. The critical detail: if `backup:clean` fails, exits with an error, or never runs, `backup:run` completes successfully anyway. They are independent processes.

## Common Failure Modes

**Cleanup disk unreachable.** Your backup retention policy includes S3 as a destination. On a cold morning, your S3 IAM role temporary credentials expire and are not renewed by the instance metadata service. `backup:run` uploads successfully (it uses different credentials or cached tokens), but `backup:clean` tries to list S3 files, fails to connect, and exits with a connection error. The next night, `backup:run` succeeds, `backup:clean` fails again, and the cycle continues. You accumulate one backup per day.

**Corrupted backup file blocks cleanup.** One of your older backup archives is corrupt (incomplete upload from a previous S3 timeout). When `backup:clean` tries to evaluate whether to delete it, it reads the zip file header, detects corruption, and crashes. The entire cleanup process aborts. You now have the corrupt file plus all the files that weren't evaluated for deletion. Spatie's cleanup should handle this more gracefully, but in practice, corrupt files in the backup set can block cleanup of the entire set.

**Retention policy misconfigured.** A developer changes `keep_all_backups_for_days` from `7` to `70` as part of a compliance requirement, but doesn't increase the cleanup frequency. With a daily backup frequency, this means 70 days of backups accumulate before the monthly retention policy begins pruning. Cleanup runs, but it's keeping everything for 70 days, not 7. Storage costs climb while the job reports success.

**Cleanup runs as wrong user.** You schedule `backup:clean` via cron as root or a privileged user. The next server rebuild resets file permissions on the backup directory. The cleanup job can write to S3 (via IAM) but cannot list S3 objects to determine what to delete (requires `s3:ListBucket` permission, which is separate from `s3:PutObject`). The job fails with a permissions error that nobody sees because cron output is redirected.

## Building Visibility Into backup:clean

The most reliable check: count the backup files and compare against your retention policy. If you expect 7 daily backups plus 4 weekly, you should have roughly 11 archives at any given time:

```php
Schedule::call(function () {
    $disk = Storage::disk('s3');
    $zipFiles = collect($disk->files('laravel-backup'))
        ->filter(fn ($file) => str_ends_with($file, '.zip'));

    $count = $zipFiles->count();
    $oldestDate = $zipFiles
        ->map(fn ($file) => $disk->lastModified($file))
        ->min();

    $daysOld = now()->diffInDays(
        Carbon::createFromTimestamp($oldestDate)
    );

    Log::info("Backup cleanup check", [
        'file_count' => $count,
        'oldest_backup_days_ago' => $daysOld,
    ]);

    // Alert if more files than expected (cleanup not running)
    if ($count > 20) {
        // Crontinel heartbeat - this fires the alert
        Http::get(env('CRONTINEL_CLEAN_ENDPOINT'));
    }
})->dailyAt('06:00');
```

The logic here is inverted from `backup:run` monitoring. Instead of alerting on absence of success, you're alerting on presence of too many files. If `backup:clean` is working, your file count stays bounded.

## Detecting When backup:clean Fails

Combine the count check with a time-window check: if the oldest backup is more than `keep_all_backups_for_days + 1` days old, cleanup either hasn't run or isn't deleting anything:

```php
$maxRetentionDays = config('backup.cleanup.default_strategy.keep_all_backups_for_days', 7);

if ($daysOld > $maxRetentionDays + 2) {
    // oldest backup is older than our retention policy allows
    // either cleanup never ran, or it's failing silently
    Log::warning("Backup cleanup may have failed", [
        'oldest_backup_days_ago' => $daysOld,
        'expected_max_days' => $maxRetentionDays,
    ]);
}
```

Pair this with a direct check: after `backup:clean` runs, verify the file count decreased:

```bash
# Store backup count before and after cleanup
BEFORE=$(aws s3 ls s3://your-bucket/laravel-backup/ | grep -c '\.zip$')
php artisan backup:clean
AFTER=$(aws s3 ls s3://your-bucket/laravel-backup/ | grep -c '\.zip$')

if [ "$AFTER" -ge "$BEFORE" ]; then
    echo "Backup cleanup did not reduce file count - possible failure"
    # trigger alert
fi
```

## Quick Setup with Crontinel

Schedule both backup and cleanup in the same monitoring context:

```php
// config/backup.php - ensure cleanup is scheduled
Schedule::command('backup:run')->dailyAt('03:00')->withoutOverlapping()->onOneServer();
Schedule::command('backup:clean')->dailyAt('04:00')->withoutOverlapping()->onOneServer();
```

Crontinel's Laravel package includes a dedicated `backup-clean` heartbeat:

```php
Schedule::command('backup:clean')
    ->dailyAt('04:00')
    ->withoutOverlapping()
    ->onOneServer()
    ->thenPing(env('CRONTINEL_CLEAN_ENDPOINT'));
```

If `backup:clean` exits with an error, or if it never runs (your monitoring window closes without a ping), Crontinel fires an alert. The dual-check approach - counting files + monitoring the job itself - catches cleanup failures from every angle: corrupted files, permission errors, unreachable disks, and misconfigured retention policies.

Storage costs from accumulating backups are the silent version of data loss. You're not losing data, but you're paying for it every month.
