{"record":{"id":"1e7c4688f3cd604f","repo":"alibaba/spring-ai-alibaba","slug":"oss-bucket-should-be-set","errorCode":null,"errorMessage":"oss bucket should be set.","messagePattern":"oss bucket should be set\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":500,"severity":"critical","filePath":"spring-ai-alibaba-admin/spring-ai-alibaba-admin-server-core/src/main/java/com/alibaba/cloud/ai/studio/core/base/manager/OssManager.java","lineNumber":342,"sourceCode":"\t}\n\n\tpublic static String trimObjectName(String objectName) {\n\t\tif (objectName == null || objectName.trim().isEmpty()) {\n\t\t\treturn null;\n\t\t}\n\t\telse {\n\t\t\treturn objectName;\n\t\t}\n\t}\n\n\tprivate String getEndpoint() {\n\t\treturn properties.getOss().getEndpoint();\n\t}\n\n\tprivate String getBucket() {\n\t\tString bucket = properties.getOss().getBucket();\n\t\tif (StringUtils.isBlank(bucket)) {\n\t\t\tthrow new IllegalArgumentException(\"oss bucket should be set.\");\n\t\t}\n\n\t\treturn bucket;\n\t}\n\n}\n","sourceCodeStart":324,"sourceCodeEnd":349,"githubUrl":"https://github.com/alibaba/spring-ai-alibaba/blob/f82da0b50f35744c13968191be2b1cd2452ef550/spring-ai-alibaba-admin/spring-ai-alibaba-admin-server-core/src/main/java/com/alibaba/cloud/ai/studio/core/base/manager/OssManager.java#L324-L349","documentation":"OssManager.getBucket is a private accessor that throws IllegalArgumentException('oss bucket should be set.') when properties.getOss().getBucket() is blank. It is invoked by the endpoint/bucket helpers whenever an OSS operation needs a bucket name, so any OSS operation (download, generateURL) on a misconfigured deployment will surface this at call time.","triggerScenarios":"Performing any OSS operation when oss.bucket is unset/blank in configuration — e.g. generateURL or downloadFile on an instance where the bucket was never configured (also affects the startup client wiring path via bucketName).","commonSituations":"Fresh deployment where only ak/sk were configured but bucket omitted; copying config between environments where bucket names differ; YAML indentation error putting bucket under the wrong key; bucket deleted and config value removed.","solutions":["Set the oss.bucket property to an existing OSS bucket in your configuration","Verify the YAML structure places bucket under the correct oss config block","Create the bucket in the target region if it does not exist and configure its name","Add a startup validation (or rely on afterPropertiesSet patterns) to fail fast on missing bucket"],"exampleFix":"// before (application.yml)\noss:\n  access-key-id: ${OSS_AK}\n  access-key-secret: ${OSS_SK}\n// after\noss:\n  access-key-id: ${OSS_AK}\n  access-key-secret: ${OSS_SK}\n  bucket: my-agent-studio-bucket\n  region: cn-beijing","handlingStrategy":"validation","validationCode":"if (props.getOss() == null || props.getOss().getBucket() == null\n    || props.getOss().getBucket().isBlank()) {\n    throw new IllegalStateException(\"Set oss.bucket before using OSS features\");\n}","typeGuard":"boolean ossBucketConfigured(OssProperties props) {\n    return props != null && props.getOss() != null\n        && props.getOss().getBucket() != null\n        && !props.getOss().getBucket().isBlank();\n}","tryCatchPattern":"try {\n    return ossManager.generateURL(objectName);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"oss bucket should be set\")) {\n        throw new ConfigurationException(\"OSS bucket missing in config\", e);\n    }\n    throw e;\n}","preventionTips":["Include bucket (and region) alongside ak/sk in every environment's config","Assert required OSS properties at deploy time before services start","Watch YAML indentation so bucket lands under the correct oss block","Create the bucket first and store its exact name in config"],"tags":["oss","configuration","bucket","startup"],"backgroundTag":"missing-required-config-field","analyzedSha":"f82da0b50f35744c13968191be2b1cd2452ef550","analyzedAt":"2026-09-09T15:32:42.421Z","contentChangedAt":"2026-09-09T15:32:42.421Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}