alibaba/spring-ai-alibaba · error · BizException

OSS_DOWNLOAD_ERROR

OSS_DOWNLOAD_ERROR

Error message

OSS download error

What it means

OssManager.downloadFile wraps any failure to fetch an OSS object to a local file in BizException(OSS_DOWNLOAD_ERROR, 'OSS download error'). It calls ossClientInternal.getObject(GetObjectRequest(bucketName, objectName), new File(path)); any exception (object missing, no permission, network, invalid object name) is caught, logged, and rethrown as this BizException with the cause attached.

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

			}
		}
	}

	/**
	 * download file from oss
	 * @param objectName object name
	 * @param path downloaded local path
	 */
	public void downloadFile(String objectName, String path) {
		long start = System.currentTimeMillis();
		try {
			String bucketName = getBucket();
			ossClientInternal.getObject(new GetObjectRequest(bucketName, objectName), new File(path));
			LogUtils.monitor("ossManager", "downloadFile", start, SUCCESS, path, objectName, path);
		}
		catch (Exception e) {
			LogUtils.monitor("ossManager", "downloadFile", start, SUCCESS, path, e.getMessage(), e);
			throw new BizException(ErrorCode.OSS_DOWNLOAD_ERROR.toError(), e);
		}
	}

	public String generateURL(String objectName) {
		long start = System.currentTimeMillis();
		String safeObjectName = trimObjectName(objectName);
		if (StringUtils.isBlank(objectName)) {
			throw new IllegalArgumentException("oss object name is invalid");
		}

		try {
			String bucketName = getBucket();
			Date expiration = new Date(System.currentTimeMillis() + URl_EXPIRE_TIME.toMillis());
			URL url = ossClient.generatePresignedUrl(bucketName, safeObjectName, expiration);
			LogUtils.monitor("ossManager", "generateURL", start, SUCCESS, objectName, url);
			return url.toString().replace("http://", "https://");
		}
		catch (Exception e) {

View on GitHub (pinned to f82da0b50f)

Solutions

1. Check the cause exception (e.g. OSSException NoSuchKey vs 403 AccessDenied) in the log/cause chain
2. Verify objectName exactly matches the key stored (no leading-slash or encoding drift)
3. Confirm the access key has oss:GetObject permission on the bucket
4. Ensure the local path's parent directory exists and is writable
5. Check network/endpoint reachability and retry for transient failures

Example fix

// before
ossManager.downloadFile(localPath, objectName);
// after
try {
    ossManager.downloadFile(localPath, objectName);
} catch (BizException e) {
    if (e.getCause() != null && String.valueOf(e.getCause()).contains("NoSuchKey")) {
        log.warn("Object {} missing in OSS, using default", objectName);
    } else {
        throw e;
    }
}

File parent = new File(path).getParentFile();
if (parent != null && !parent.exists()) parent.mkdirs(); // ensure local target writable

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

try {
    ossManager.downloadFile(path, objectName);
} catch (BizException e) {
    if (String.valueOf(e.getCause()).contains("NoSuchKey")) {
        log.warn("Object {} not found in OSS", objectName);
    } else {
        throw e;
    }
}

When it happens

Trigger: Calling downloadFile(path, objectName) when the object does not exist in the bucket, the credentials lack GetObject permission, the network to OSS fails, or the local path is not writable.

Common situations: Requesting a file key that was never uploaded or was deleted; typo in objectName; 404 NoSuchKey from OSS; bucket access revoked; local directory of path does not exist; firewall blocking the OSS endpoint.

Related errors

• OSS_UPLOAD_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/9eb68c966982f41f. Report an issue: GitHub.