coollabsio/coolify · error · RuntimeException

S3 bucket name is not allowed: {error}

Error message

S3 bucket name is not allowed: {error}

What it means

Thrown by S3Storage::testConnection() (app/Models/S3Storage.php:185). The bucket name is validated by the ValidS3BucketName rule before any S3 request is made: 3–63 characters, lowercase letters/numbers/dots/hyphens only, must start and end with a letter or number, no consecutive dots, no dot-hyphen pairs, and must not look like an IPv4 address. Any violation aborts the connection test, sets is_usable=false, and (once per storage) triggers an 'S3 Storage Connection Error' email to team admins/owners via toUserFriendlyConnectionException().

Source

Thrown at app/Models/S3Storage.php:185

    public function testConnection(bool $shouldSave = false)
    {
        try {
            $validator = Validator::make(
                [
                    'endpoint' => $this['endpoint'],
                    'bucket' => $this['bucket'],
                ],
                [
                    'endpoint' => ['required', new SafeWebhookUrl(trustedInternalHosts: $this->trustedInternalHosts())],
                    'bucket' => ['required', new ValidS3BucketName],
                ],
            );
            $validator->fails();
            if ($validator->errors()->has('endpoint')) {
                throw new \RuntimeException('S3 endpoint is not allowed: '.$validator->errors()->first('endpoint'));
            }
            if ($validator->errors()->has('bucket')) {
                throw new \RuntimeException('S3 bucket name is not allowed: '.$validator->errors()->first('bucket'));
            }

            $disk = $this->filesystem();
            // Test the connection by listing files with ListObjectsV2 (S3)
            $disk->files();

            $this->unusable_email_sent = false;
            $this->is_usable = true;
        } catch (\Throwable $e) {
            $exception = $this->toUserFriendlyConnectionException($e);
            $this->is_usable = false;
            if ($this->unusable_email_sent === false && is_transactional_emails_enabled()) {
                try {
                    $mail = new MailMessage;
                    $mail->subject('Coolify: S3 Storage Connection Error');
                    $mail->view('emails.s3-connection-error', ['name' => $this->name, 'reason' => $exception->getMessage(), 'url' => route('storage.show', ['storage_uuid' => $this->uuid])]);

                    // Load the team with its members and their roles explicitly

View on GitHub (pinned to 70b9acc424)

Solutions

1. Rename to a compliant bucket: lowercase, 3–63 chars, letters/digits/dots/hyphens, no underscores/uppercase.
2. Check start/end characters and remove consecutive dots or '.-' pairs.
3. Re-run the connection test (Test connection / testConnection(true)) — it re-validates before touching the network.

Example fix

// before
$storage->update(['bucket' => 'My_Backup_Bucket']);
$storage->testConnection(); // S3 bucket name is not allowed

// after
$storage->update(['bucket' => 'my-backup-bucket']);
$storage->testConnection();

// Validate the bucket client-side with the same rule
use App\Rules\ValidS3BucketName;
Validator::validate(['bucket' => $bucket], ['bucket' => ['required', new ValidS3BucketName]]);

// Or a quick regex precheck: /^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$/ plus no '..' / '.-' / IP shape

try {
    $storage->testConnection();
} catch (\Throwable $e) {
    if (str_contains($e->getMessage(), 'bucket name is not allowed')) {
        return 'Use a lowercase, 3–63 char bucket name with letters, digits, dots and hyphens only.';
    }
    throw $e;
}

When it happens

Trigger: Saving/testing an S3 storage whose bucket contains uppercase letters, underscores, is shorter than 3 or longer than 63 chars, starts/ends with a dot or hyphen, has '..' or '.-' sequences, or is an IP-shaped string like '192.168.1.1'.

Common situations: Copying bucket names that work on-prem (MinIO is case-tolerant) into Coolify; underscores from older S3-compatible naming; typos with spaces (note the bucket setter trims outer whitespace only).

Related errors

• S3 endpoint is not allowed: {error}
• Invalid Cron / Human expression
• The backup target is not a directory or persistent volume.
• The directory backup workdir is unavailable.
• Pre-deployment command: Could not find a valid container. Is

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