{"record":{"id":"58f1c6a07e0091b4","repo":"vitessio/vitess","slug":"s3-backup-storage-bucket-required","errorCode":null,"errorMessage":"--s3-backup-storage-bucket required","messagePattern":"--s3-backup-storage-bucket required","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"go/vt/mysqlctl/s3backupstorage/s3.go","lineNumber":601,"sourceCode":"\t\t\t\to.UsePathStyle = forcePath\n\t\t\t\tif retryCount >= 0 {\n\t\t\t\t\to.RetryMaxAttempts = retryCount\n\t\t\t\t\to.Retryer = &ClosedConnectionRetryer{\n\t\t\t\t\t\tawsRetryer: retry.NewStandard(func(options *retry.StandardOptions) {\n\t\t\t\t\t\t\toptions.MaxAttempts = retryCount\n\t\t\t\t\t\t}),\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t},\n\t\t}\n\t\tif endpoint != \"\" {\n\t\t\toptions = append(options, s3.WithEndpointResolverV2(newEndpointResolver()))\n\t\t}\n\n\t\tbs._client = s3.NewFromConfig(cfg, options...)\n\n\t\tif len(bucket) == 0 {\n\t\t\treturn nil, errors.New(\"--s3-backup-storage-bucket required\")\n\t\t}\n\n\t\tif _, err := bs._client.HeadBucket(context.Background(), &s3.HeadBucketInput{Bucket: &bucket}); err != nil {\n\t\t\treturn nil, err\n\t\t}\n\n\t\tif err := bs.s3SSE.init(); err != nil {\n\t\t\treturn nil, err\n\t\t}\n\t}\n\treturn bs._client, nil\n}\n\nfunc objName(parts ...string) string {\n\tres := \"\"\n\tif root != \"\" {\n\t\tres += root + delimiter\n\t}","sourceCodeStart":583,"sourceCodeEnd":619,"githubUrl":"https://github.com/vitessio/vitess/blob/01a25a7d176f94613b8d59d799f438380a8760e4/go/vt/mysqlctl/s3backupstorage/s3.go#L583-L619","documentation":"The S3 backup storage client requires a target bucket. When --s3-backup-storage-bucket (config bucket) is empty, client() returns this error instead of attempting S3 calls, because every operation (list/upload/delete) needs a bucket name.","triggerScenarios":"Calling ListBackups, StartBackup, or RemoveBackup when the S3 backup storage was constructed without a bucket configured — i.e. the --s3-backup-storage-bucket flag was not set (or derived bucket value is empty).","commonSituations":"Deploying a vttablet/vtbackup with s3 backup storage enabled but forgetting the bucket flag; renaming/migrating flags across versions; environment-specific config files missing the bucket entry; empty-string env expansion in a config template.","solutions":["Set the --s3-backup-storage-bucket flag to your S3 bucket name","Verify the config template/tooling actually interpolates the bucket value (not empty string)","Restart/reinitialize the storage client after adding the flag so it passes validation and HeadBucket"],"exampleFix":"// before (tablet init flags)\n-backup_storage_implementation s3\n// after\n-backup_storage_implementation s3\n-s3_backup_storage_bucket my-vitess-backups","handlingStrategy":"validation","validationCode":"bucket := viper.GetString(\"s3-backup-storage-bucket\")\nif bucket == \"\" {\n    return fmt.Errorf(\"--s3-backup-storage-bucket must be set before using S3 backup storage\")\n}","typeGuard":null,"tryCatchPattern":"_, err := bs.ListBackups(ctx)\nif err != nil && strings.Contains(err.Error(), \"--s3-backup-storage-bucket required\") {\n    return fmt.Errorf(\"misconfiguration: set --s3-backup-storage-bucket: %w\", err)\n}","preventionTips":["Validate all backup-related flags at process startup (fail fast in PreRunE)","Render config templates with strict mode so empty interpolations error out","Document the required S3 flags alongside backup_storage_implementation=s3","Add a smoke test that initializes storage with production-like flags"],"tags":["s3","configuration","missing-flag","backup"],"backgroundTag":"missing-required-config","analyzedSha":"01a25a7d176f94613b8d59d799f438380a8760e4","analyzedAt":"2026-09-01T17:28:30.605Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}