What causes "--s3-backup-storage-bucket required" in vitessio/vitess?

Set the --s3-backup-storage-bucket flag to your S3 bucket name

--s3-backup-storage-bucket required

Error message

--s3-backup-storage-bucket required

What it means

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.

Source

Thrown at go/vt/mysqlctl/s3backupstorage/s3.go:601

				o.UsePathStyle = forcePath
				if retryCount >= 0 {
					o.RetryMaxAttempts = retryCount
					o.Retryer = &ClosedConnectionRetryer{
						awsRetryer: retry.NewStandard(func(options *retry.StandardOptions) {
							options.MaxAttempts = retryCount
						}),
					}
				}
			},
		}
		if endpoint != "" {
			options = append(options, s3.WithEndpointResolverV2(newEndpointResolver()))
		}

		bs._client = s3.NewFromConfig(cfg, options...)

		if len(bucket) == 0 {
			return nil, errors.New("--s3-backup-storage-bucket required")
		}

		if _, err := bs._client.HeadBucket(context.Background(), &s3.HeadBucketInput{Bucket: &bucket}); err != nil {
			return nil, err
		}

		if err := bs.s3SSE.init(); err != nil {
			return nil, err
		}
	}
	return bs._client, nil
}

func objName(parts ...string) string {
	res := ""
	if root != "" {
		res += root + delimiter
	}

View on GitHub (pinned to 01a25a7d17)

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

Example fix

// before (tablet init flags)
-backup_storage_implementation s3
// after
-backup_storage_implementation s3
-s3_backup_storage_bucket my-vitess-backups

Defensive patterns

Strategy: validation

Validate before calling

bucket := viper.GetString("s3-backup-storage-bucket")
if bucket == "" {
    return fmt.Errorf("--s3-backup-storage-bucket must be set before using S3 backup storage")
}

Try / catch

_, err := bs.ListBackups(ctx)
if err != nil && strings.Contains(err.Error(), "--s3-backup-storage-bucket required") {
    return fmt.Errorf("misconfiguration: set --s3-backup-storage-bucket: %w", err)
}

Prevention

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

When it happens

Trigger: 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).

Common situations: 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.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

AI-assisted analysis of vitessio/vitess@01a25a7d17 (2026-09-01). Data as JSON: /api/errors/58f1c6a07e0091b4. Report an issue: GitHub.