{"record":{"id":"93c66f5db0474965","repo":"benbjohnson/litestream","slug":"bucket-required-for-oss-replica","errorCode":null,"errorMessage":"bucket required for oss replica","messagePattern":"bucket required for oss replica","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/litestream/main.go","lineNumber":2028,"sourceCode":"\t\t)\n\n\t\tubucket, uregion, _ = oss.ParseHost(host)\n\n\t\t// Only apply URL parts to fields that have not been overridden.\n\t\tif configPath == \"\" {\n\t\t\tconfigPath = upath\n\t\t}\n\t\tif bucket == \"\" {\n\t\t\tbucket = ubucket\n\t\t}\n\t\tif region == \"\" {\n\t\t\tregion = uregion\n\t\t}\n\t}\n\n\t// Ensure required settings are set.\n\tif bucket == \"\" {\n\t\treturn nil, fmt.Errorf(\"bucket required for oss replica\")\n\t}\n\n\t// Build replica client.\n\tclient := oss.NewReplicaClient()\n\tclient.AccessKeyID = c.AccessKeyID\n\tclient.AccessKeySecret = c.SecretAccessKey\n\tclient.Bucket = bucket\n\tclient.Path = configPath\n\tclient.Region = region\n\tclient.Endpoint = endpoint\n\n\t// Apply upload configuration if specified.\n\tif c.PartSize != nil {\n\t\tclient.PartSize = int64(*c.PartSize)\n\t}\n\tif c.Concurrency != nil {\n\t\tclient.Concurrency = *c.Concurrency\n\t}","sourceCodeStart":2010,"sourceCodeEnd":2046,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/cmd/litestream/main.go#L2010-L2046","documentation":"After resolving the bucket from either the URL or the `bucket` config field, newOSSReplicaClientFromConfig found neither set. An OSS replica cannot determine which bucket to use, so client construction fails.","triggerScenarios":"Configuring an OSS replica with only `region`/`endpoint`/credentials but no `bucket` and a URL without a bucket component.","commonSituations":"Writing `oss://` with no bucket; forgetting the bucket key entirely when first setting up OSS; env-based config where the bucket variable expands to empty.","solutions":["Add `bucket: <name>` to the OSS replica config.","Use a full URL form: `url: oss://<bucket>/<path>`.","Verify the environment variable feeding the bucket expands to a non-empty value."],"exampleFix":"# before\nreplicas:\n  - type: oss\n    region: cn-hangzhou\n# after\nreplicas:\n  - type: oss\n    region: cn-hangzhou\n    bucket: my-db-backups","handlingStrategy":"validation","validationCode":"// Ensure the OSS bucket resolves to a non-empty value before starting\nif cfg.Bucket == \"\" && !strings.HasPrefix(strings.TrimPrefix(cfg.URL, \"oss://\"), validBucketName) {\n    return fmt.Errorf(\"oss replica bucket missing\")\n}","typeGuard":null,"tryCatchPattern":"if err := runReplicate(); err != nil {\n    if strings.Contains(err.Error(), \"bucket required for oss\") {\n        // add bucket to config or URL\n    }\n}","preventionTips":["Set bucket explicitly in the replica block; avoid relying on env vars that may be unset.","Validate config with a dry run before deploying to production."],"tags":["oss","config","missing-field","replica"],"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"}