alibaba/spring-ai-alibaba · error · BizException

OSS_UPLOAD_ERROR

OSS_UPLOAD_ERROR

Error message

OSS upload error

What it means

OssManager.uploadFile wraps any failure of the Alibaba Cloud OSS putObject operation in BizException(OSS_UPLOAD_ERROR, 'OSS upload error'). The OSSException branch covers server/client-side errors reported by the OSS SDK (bucket missing, permissions, invalid key). A second catch-all branch wraps any other exception (stream problems, network failures). Both log the upload path before throwing.

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:175

	public String uploadFile(String type, String uid, String path) {
		long start = System.currentTimeMillis();

		BufferedInputStream bis = null;
		try {
			File file = new File(path);
			bis = new BufferedInputStream(new FileInputStream(file));
			String name = getObjectName(uid, type, file.getName());

			String bucketName = getBucket();
			PutObjectRequest request = new PutObjectRequest(bucketName, name, bis);
			PutObjectResult putObjectResult = ossClientInternal.putObject(request);
			LogUtils.monitor("ossManager", "uploadFile", start, SUCCESS, path, putObjectResult);

			return name;
		}
		catch (OSSException e) {
			LogUtils.monitor("ossManager", "uploadFile", start, SUCCESS, path, e.getMessage(), e.getRequestId(), e);
			throw new BizException(ErrorCode.OSS_UPLOAD_ERROR.toError(), e);
		}
		catch (Exception e) {
			LogUtils.monitor("ossManager", "uploadFile", start, SUCCESS, path, e);
			throw new BizException(ErrorCode.OSS_UPLOAD_ERROR.toError(), e);
		}
		finally {
			if (bis != null) {
				IOUtils.closeQuietly(bis);
			}
		}
	}

	/**
	 * download file from oss
	 * @param objectName object name
	 * @param path downloaded local path
	 */
	public void downloadFile(String objectName, String path) {

View on GitHub (pinned to f82da0b50f)

Solutions

1. Check the OSSException requestId and SDK message in the logs to identify the underlying OSS error code
2. Verify oss.bucket, oss.endpoint and oss.region in config point to an existing bucket
3. Grant the access key's RAM role oss:PutObject permission on the bucket
4. Test network reachability to the OSS endpoint (VPC vs public endpoint)
5. Retry the upload for transient network errors

Example fix

// before
ossManager.uploadFile(inputStream, path);
// after
try {
    ossManager.uploadFile(inputStream, path);
} catch (BizException e) {
    if (e.getError().getCode().equals("OSS_UPLOAD_ERROR")) {
        log.warn("OSS upload failed, check bucket/credentials", e);
        throw new StorageException("Failed to upload " + path, e);
    }
    throw e;
}

if (properties.getOss().getBucket() == null || properties.getOss().getBucket().isBlank())
    throw new IllegalStateException("OSS bucket not configured");

boolean isOssUploadFailure(BizException e) {
    return e.getError() != null && "OSS_UPLOAD_ERROR".equals(e.getError().getCode());
}

try {
    ossManager.uploadFile(in, path);
} catch (BizException e) {
    if (isOssUploadFailure(e) && e.getCause() instanceof OSSException ose) {
        log.error("OSS rejected upload, requestId={}", ose.getRequestId(), ose);
    }
    throw e;
}

When it happens

Trigger: Calling uploadFile when the target bucket does not exist, the credentials lack PutObject permission, the network to the OSS endpoint fails, or the input stream is unreadable.

Common situations: Bucket deleted or region mismatch between config and bucket; RAM policy missing oss:PutObject; endpoint misconfigured (internal vs public endpoint); file larger than limits; connection timeout in restricted network environments.

Related errors

• OSS_DOWNLOAD_ERROR
• OSS_GEN_URL_ERROR
• oss object name is invalid
• oss ak or sk should be set.
• oss bucket should be set.

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