{"record":{"id":"9eb68c966982f41f","repo":"alibaba/spring-ai-alibaba","slug":"oss-download-error","errorCode":"OSS_DOWNLOAD_ERROR","errorMessage":"OSS download error","messagePattern":"OSS download error","errorType":"error_code","errorClass":"BizException","httpStatus":null,"severity":"error","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":202,"sourceCode":"\t\t\t}\n\t\t}\n\t}\n\n\t/**\n\t * download file from oss\n\t * @param objectName object name\n\t * @param path downloaded local path\n\t */\n\tpublic void downloadFile(String objectName, String path) {\n\t\tlong start = System.currentTimeMillis();\n\t\ttry {\n\t\t\tString bucketName = getBucket();\n\t\t\tossClientInternal.getObject(new GetObjectRequest(bucketName, objectName), new File(path));\n\t\t\tLogUtils.monitor(\"ossManager\", \"downloadFile\", start, SUCCESS, path, objectName, path);\n\t\t}\n\t\tcatch (Exception e) {\n\t\t\tLogUtils.monitor(\"ossManager\", \"downloadFile\", start, SUCCESS, path, e.getMessage(), e);\n\t\t\tthrow new BizException(ErrorCode.OSS_DOWNLOAD_ERROR.toError(), e);\n\t\t}\n\t}\n\n\tpublic String generateURL(String objectName) {\n\t\tlong start = System.currentTimeMillis();\n\t\tString safeObjectName = trimObjectName(objectName);\n\t\tif (StringUtils.isBlank(objectName)) {\n\t\t\tthrow new IllegalArgumentException(\"oss object name is invalid\");\n\t\t}\n\n\t\ttry {\n\t\t\tString bucketName = getBucket();\n\t\t\tDate expiration = new Date(System.currentTimeMillis() + URl_EXPIRE_TIME.toMillis());\n\t\t\tURL url = ossClient.generatePresignedUrl(bucketName, safeObjectName, expiration);\n\t\t\tLogUtils.monitor(\"ossManager\", \"generateURL\", start, SUCCESS, objectName, url);\n\t\t\treturn url.toString().replace(\"http://\", \"https://\");\n\t\t}\n\t\tcatch (Exception e) {","sourceCodeStart":184,"sourceCodeEnd":220,"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#L184-L220","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the cause exception (e.g. OSSException NoSuchKey vs 403 AccessDenied) in the log/cause chain","Verify objectName exactly matches the key stored (no leading-slash or encoding drift)","Confirm the access key has oss:GetObject permission on the bucket","Ensure the local path's parent directory exists and is writable","Check network/endpoint reachability and retry for transient failures"],"exampleFix":"// before\nossManager.downloadFile(localPath, objectName);\n// after\ntry {\n    ossManager.downloadFile(localPath, objectName);\n} catch (BizException e) {\n    if (e.getCause() != null && String.valueOf(e.getCause()).contains(\"NoSuchKey\")) {\n        log.warn(\"Object {} missing in OSS, using default\", objectName);\n    } else {\n        throw e;\n    }\n}","handlingStrategy":"try-catch","validationCode":"File parent = new File(path).getParentFile();\nif (parent != null && !parent.exists()) parent.mkdirs(); // ensure local target writable","typeGuard":"boolean isOssDownloadFailure(BizException e) {\n    return e.getError() != null && \"OSS_DOWNLOAD_ERROR\".equals(e.getError().getCode());\n}","tryCatchPattern":"try {\n    ossManager.downloadFile(path, objectName);\n} catch (BizException e) {\n    if (String.valueOf(e.getCause()).contains(\"NoSuchKey\")) {\n        log.warn(\"Object {} not found in OSS\", objectName);\n    } else {\n        throw e;\n    }\n}","preventionTips":["Head the object (or list) to confirm existence before download","Grant oss:GetObject to the configured credentials","Ensure the local target path's parent directory exists","Retry transient network failures"],"tags":["oss","storage","download"],"backgroundTag":"api-error-response","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"}