laravel/framework · error · RuntimeException

DynamoDb does not support flushing an entire table. Please c

Error message

DynamoDb does not support flushing an entire table. Please create a new table.

What it means

DynamoDbStore::flush() unconditionally throws RuntimeException because DynamoDB has no efficient 'delete all rows' operation and a Scan+Delete loop would be prohibitively expensive. The framework refuses to flush and instructs creating a new table instead.

Source

Thrown at src/Illuminate/Cache/DynamoDbStore.php:519

                $this->keyAttribute => [
                    'S' => $this->prefix.$key,
                ],
            ],
        ]);

        return true;
    }

    /**
     * Remove all items from the cache.
     *
     * @return never
     *
     * @throws \RuntimeException
     */
    public function flush()
    {
        throw new RuntimeException('DynamoDb does not support flushing an entire table. Please create a new table.');
    }

    /**
     * Get the UNIX timestamp for the given number of seconds.
     *
     * @param  int  $seconds
     * @return int
     */
    protected function toTimestamp($seconds)
    {
        return $seconds > 0
            ? $this->availableAt($seconds)
            : $this->currentTime();
    }

    /**
     * Serialize the value.
     *

View on GitHub (pinned to bd6b5437e6)

Solutions

Do not call flush() on DynamoDB stores; instead delete and recreate the table (CloudFormation/CDK/IaC) to reset.
For tests, use a separate DynamoDB table (or the array driver) and tear it down rather than flushing.
If selective clearing is needed, iterate keys and forget() each (Scan then batch DeleteItem).
Point CACHE_STORE at a non-dynamodb driver in environments that need flush() (e.g. testing).

Example fix

// before
Cache::store('dynamodb')->flush(); // always throws

// after
// Option A: drop & recreate the table via AWS CLI/IaC
aws dynamodb delete-table --table-name cache
aws dynamodb create-table ... # via CloudFormation

// Option B: forget specific keys
foreach ($keys as $k) {
    Cache::store('dynamodb')->forget($k);
}

Defensive patterns

Strategy: validation

Validate before calling

if (Cache::store('dynamodb')->getStore() instanceof \Illuminate\Cache\DynamoDbStore) {
    throw new \RuntimeException('Cannot flush DynamoDB cache; recreate the table instead.');
}
Cache::flush();

Type guard

function cacheSupportsFlush(string $storeName): bool
{
    $store = Cache::store($storeName)->getStore();
    return ! ($store instanceof \Illuminate\Cache\DynamoDbStore);
}

Try / catch

try {
    Cache::store('dynamodb')->flush();
} catch (\RuntimeException $e) {
    if (str_contains($e->getMessage(), 'DynamoDb does not support flushing')) {
        // recreate table via IaC, or forget() individual keys
    } else {
        throw $e;
    }
}

Prevention

Never call flush() on DynamoDB stores.
Use array/file drivers in tests to allow teardown.
Automate table recreation via CloudFormation/CDK.
Document DynamoDB cache limitations for ops.

When it happens

Trigger: Calling Cache::store('dynamodb')->flush(), Artisan cache:clear resolving to a dynamodb store, or any reset/test teardown that invokes flush() on a DynamoDB-backed cache. The throw happens every time flush() is called regardless of contents.

Common situations: Running php artisan cache:clear in a test/staging environment whose CACHE_STORE=dynamodb. Sharing a DynamoDB table across environments and attempting to clear one. CI pipelines that flush caches between runs.

Related errors

AI-assisted analysis of laravel/framework@bd6b5437e6 (2026-08-06). Data as JSON: /data/errors/97b19867858573e9.json. Report an issue: GitHub.