{"record":{"id":"78db3794741106b5","repo":"benbjohnson/litestream","slug":"oss-bucket-name-is-required","errorCode":null,"errorMessage":"oss: bucket name is required","messagePattern":"oss: bucket name is required","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"oss/replica_client.go","lineNumber":123,"sourceCode":"}\n\n// Type returns \"oss\" as the client type.\nfunc (c *ReplicaClient) Type() string {\n\treturn ReplicaClientType\n}\n\n// Init initializes the connection to OSS. No-op if already initialized.\nfunc (c *ReplicaClient) Init(ctx context.Context) (err error) {\n\tc.mu.Lock()\n\tdefer c.mu.Unlock()\n\n\tif c.client != nil {\n\t\treturn nil\n\t}\n\n\t// Validate required configuration\n\tif c.Bucket == \"\" {\n\t\treturn fmt.Errorf(\"oss: bucket name is required\")\n\t}\n\n\t// Use default region if not specified\n\tregion := c.Region\n\tif region == \"\" {\n\t\tregion = DefaultRegion\n\t}\n\n\t// Build configuration\n\tcfg := oss.LoadDefaultConfig()\n\n\t// Configure credentials\n\tif c.AccessKeyID != \"\" && c.AccessKeySecret != \"\" {\n\t\tcfg = cfg.WithCredentialsProvider(\n\t\t\tcredentials.NewStaticCredentialsProvider(c.AccessKeyID, c.AccessKeySecret),\n\t\t)\n\t} else {\n\t\t// Use environment variable credentials provider","sourceCodeStart":105,"sourceCodeEnd":141,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/oss/replica_client.go#L105-L141","documentation":"Litestream's OSS (Alibaba Cloud) replica client requires a bucket name to construct its SDK client. Init validates configuration eagerly and returns this error when Replica.Bucket is empty, before any network call is made. It is a fail-fast config validation, not a runtime/network failure.","triggerScenarios":"Calling Init() on an oss.ReplicaClient constructed with an empty Bucket field, or via a YAML config where the replica URL omits the bucket (e.g. url lacks the oss://bucket part or bucket was dropped during $PID/env expansion of the config).","commonSituations":"Missing 'bucket' key in litestream.yml; building the client programmatically with NewReplicaClientFromURL on a malformed URL like 'oss:///path'; env var interpolation silently yielding an empty bucket; copy-pasting an S3 config into an OSS replica block.","solutions":["Set the bucket: add 'bucket: my-bucket' to the OSS replica config or set Bucket on oss.ReplicaClient before Init().","Use a full URL form: url: \"oss://my-bucket.oss-cn-hangzhou.aliyuncs.com/path\" so ParseHost extracts the bucket.","Verify the config file was actually loaded and env expansion ($VARS) produced a non-empty bucket; run 'litestream -config ... ' and inspect startup logs.","Check for typos (e.g. 'buckets' vs 'bucket') in the YAML replica section."],"exampleFix":"// before\nreplicas:\n  - type: oss\n    region: cn-hangzhou\n    path: db/ltx\n// after\nreplicas:\n  - type: oss\n    bucket: my-litestream-bucket\n    region: cn-hangzhou\n    path: db/ltx","handlingStrategy":"validation","validationCode":"if c.Bucket == \"\" {\n    return fmt.Errorf(\"oss replica misconfigured: bucket is required\")\n}\nif err := c.Init(ctx); err != nil { return err }","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always set bucket (or a full oss://bucket... URL) in the replica config before starting litestream.","Lint the config with a schema check in CI; assert bucket is non-empty after env expansion.","Prefer full oss:// URLs so bucket/region are parsed in one place."],"tags":["config","oss","startup","validation"],"backgroundTag":"missing-required-config-field","analyzedSha":"4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3","analyzedAt":"2026-09-06T18:29:25.564Z","contentChangedAt":"2026-09-06T18:29:25.564Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}