alibaba/spring-ai-alibaba · critical · IllegalArgumentException

oss bucket should be set.

Error message

oss bucket should be set.

What it means

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.

Source

Thrown at spring-ai-alibaba-admin/spring-ai-alibaba-admin-server-core/src/main/java/com/alibaba/cloud/ai/studio/core/base/manager/OssManager.java:342

	}

	public static String trimObjectName(String objectName) {
		if (objectName == null || objectName.trim().isEmpty()) {
			return null;
		}
		else {
			return objectName;
		}
	}

	private String getEndpoint() {
		return properties.getOss().getEndpoint();
	}

	private String getBucket() {
		String bucket = properties.getOss().getBucket();
		if (StringUtils.isBlank(bucket)) {
			throw new IllegalArgumentException("oss bucket should be set.");
		}

		return bucket;
	}

}

View on GitHub (pinned to f82da0b50f)

Solutions

1. Set the oss.bucket property to an existing OSS bucket in your configuration
2. Verify the YAML structure places bucket under the correct oss config block
3. Create the bucket in the target region if it does not exist and configure its name
4. Add a startup validation (or rely on afterPropertiesSet patterns) to fail fast on missing bucket

Example fix

// before (application.yml)
oss:
  access-key-id: ${OSS_AK}
  access-key-secret: ${OSS_SK}
// after
oss:
  access-key-id: ${OSS_AK}
  access-key-secret: ${OSS_SK}
  bucket: my-agent-studio-bucket
  region: cn-beijing

if (props.getOss() == null || props.getOss().getBucket() == null
    || props.getOss().getBucket().isBlank()) {
    throw new IllegalStateException("Set oss.bucket before using OSS features");
}

boolean ossBucketConfigured(OssProperties props) {
    return props != null && props.getOss() != null
        && props.getOss().getBucket() != null
        && !props.getOss().getBucket().isBlank();
}

try {
    return ossManager.generateURL(objectName);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("oss bucket should be set")) {
        throw new ConfigurationException("OSS bucket missing in config", e);
    }
    throw e;
}

When it happens

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

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

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• oss ak or sk should be set.
• 创建RestClient失败
• OSS_UPLOAD_ERROR
• OSS_DOWNLOAD_ERROR
• oss object name is invalid

AI-assisted analysis of alibaba/spring-ai-alibaba@f82da0b50f (2026-09-09). Data as JSON: /api/errors/1e7c4688f3cd604f. Report an issue: GitHub.