{"record":{"id":"12857dfddb993e81","repo":"coollabsio/coolify","slug":"s3-bucket-name-is-not-allowed-error","errorCode":null,"errorMessage":"S3 bucket name is not allowed: {error}","messagePattern":"S3 bucket name is not allowed: (.+?)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"app/Models/S3Storage.php","lineNumber":185,"sourceCode":"    public function testConnection(bool $shouldSave = false)\n    {\n        try {\n            $validator = Validator::make(\n                [\n                    'endpoint' => $this['endpoint'],\n                    'bucket' => $this['bucket'],\n                ],\n                [\n                    'endpoint' => ['required', new SafeWebhookUrl(trustedInternalHosts: $this->trustedInternalHosts())],\n                    'bucket' => ['required', new ValidS3BucketName],\n                ],\n            );\n            $validator->fails();\n            if ($validator->errors()->has('endpoint')) {\n                throw new \\RuntimeException('S3 endpoint is not allowed: '.$validator->errors()->first('endpoint'));\n            }\n            if ($validator->errors()->has('bucket')) {\n                throw new \\RuntimeException('S3 bucket name is not allowed: '.$validator->errors()->first('bucket'));\n            }\n\n            $disk = $this->filesystem();\n            // Test the connection by listing files with ListObjectsV2 (S3)\n            $disk->files();\n\n            $this->unusable_email_sent = false;\n            $this->is_usable = true;\n        } catch (\\Throwable $e) {\n            $exception = $this->toUserFriendlyConnectionException($e);\n            $this->is_usable = false;\n            if ($this->unusable_email_sent === false && is_transactional_emails_enabled()) {\n                try {\n                    $mail = new MailMessage;\n                    $mail->subject('Coolify: S3 Storage Connection Error');\n                    $mail->view('emails.s3-connection-error', ['name' => $this->name, 'reason' => $exception->getMessage(), 'url' => route('storage.show', ['storage_uuid' => $this->uuid])]);\n\n                    // Load the team with its members and their roles explicitly","sourceCodeStart":167,"sourceCodeEnd":203,"githubUrl":"https://github.com/coollabsio/coolify/blob/70b9acc42467278373e00de77abb40684e25b395/app/Models/S3Storage.php#L167-L203","documentation":"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().","triggerScenarios":"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'.","commonSituations":"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).","solutions":["Rename to a compliant bucket: lowercase, 3–63 chars, letters/digits/dots/hyphens, no underscores/uppercase.","Check start/end characters and remove consecutive dots or '.-' pairs.","Re-run the connection test (Test connection / testConnection(true)) — it re-validates before touching the network."],"exampleFix":"// before\n$storage->update(['bucket' => 'My_Backup_Bucket']);\n$storage->testConnection(); // S3 bucket name is not allowed\n\n// after\n$storage->update(['bucket' => 'my-backup-bucket']);\n$storage->testConnection();","handlingStrategy":"validation","validationCode":"// Validate the bucket client-side with the same rule\nuse App\\Rules\\ValidS3BucketName;\nValidator::validate(['bucket' => $bucket], ['bucket' => ['required', new ValidS3BucketName]]);\n\n// Or a quick regex precheck: /^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$/ plus no '..' / '.-' / IP shape","typeGuard":null,"tryCatchPattern":"try {\n    $storage->testConnection();\n} catch (\\Throwable $e) {\n    if (str_contains($e->getMessage(), 'bucket name is not allowed')) {\n        return 'Use a lowercase, 3–63 char bucket name with letters, digits, dots and hyphens only.';\n    }\n    throw $e;\n}","preventionTips":["Standardize bucket naming to lowercase-with-hyphens; never reuse names containing uppercase or underscores even if a non-AWS backend accepts them.","Run the ValidS3BucketName rule in your own form/API validation so users see the constraint before Coolify tests the connection."],"tags":["coolify","s3","validation","bucket-naming","backups"],"backgroundTag":"s3-bucket-name-invalid","analyzedSha":"70b9acc42467278373e00de77abb40684e25b395","analyzedAt":"2026-08-17T01:41:01.313Z","schemaVersion":2},"datasetVersion":"2026-08-17T04:17:16.089Z"}