{"record":{"id":"a175ee981b019c96","repo":"alibaba/spring-ai-alibaba","slug":"oss-upload-error","errorCode":"OSS_UPLOAD_ERROR","errorMessage":"OSS upload error","messagePattern":"OSS upload 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":175,"sourceCode":"\tpublic String uploadFile(String type, String uid, String path) {\n\t\tlong start = System.currentTimeMillis();\n\n\t\tBufferedInputStream bis = null;\n\t\ttry {\n\t\t\tFile file = new File(path);\n\t\t\tbis = new BufferedInputStream(new FileInputStream(file));\n\t\t\tString name = getObjectName(uid, type, file.getName());\n\n\t\t\tString bucketName = getBucket();\n\t\t\tPutObjectRequest request = new PutObjectRequest(bucketName, name, bis);\n\t\t\tPutObjectResult putObjectResult = ossClientInternal.putObject(request);\n\t\t\tLogUtils.monitor(\"ossManager\", \"uploadFile\", start, SUCCESS, path, putObjectResult);\n\n\t\t\treturn name;\n\t\t}\n\t\tcatch (OSSException e) {\n\t\t\tLogUtils.monitor(\"ossManager\", \"uploadFile\", start, SUCCESS, path, e.getMessage(), e.getRequestId(), e);\n\t\t\tthrow new BizException(ErrorCode.OSS_UPLOAD_ERROR.toError(), e);\n\t\t}\n\t\tcatch (Exception e) {\n\t\t\tLogUtils.monitor(\"ossManager\", \"uploadFile\", start, SUCCESS, path, e);\n\t\t\tthrow new BizException(ErrorCode.OSS_UPLOAD_ERROR.toError(), e);\n\t\t}\n\t\tfinally {\n\t\t\tif (bis != null) {\n\t\t\t\tIOUtils.closeQuietly(bis);\n\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) {","sourceCodeStart":157,"sourceCodeEnd":193,"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#L157-L193","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the OSSException requestId and SDK message in the logs to identify the underlying OSS error code","Verify oss.bucket, oss.endpoint and oss.region in config point to an existing bucket","Grant the access key's RAM role oss:PutObject permission on the bucket","Test network reachability to the OSS endpoint (VPC vs public endpoint)","Retry the upload for transient network errors"],"exampleFix":"// before\nossManager.uploadFile(inputStream, path);\n// after\ntry {\n    ossManager.uploadFile(inputStream, path);\n} catch (BizException e) {\n    if (e.getError().getCode().equals(\"OSS_UPLOAD_ERROR\")) {\n        log.warn(\"OSS upload failed, check bucket/credentials\", e);\n        throw new StorageException(\"Failed to upload \" + path, e);\n    }\n    throw e;\n}","handlingStrategy":"retry","validationCode":"if (properties.getOss().getBucket() == null || properties.getOss().getBucket().isBlank())\n    throw new IllegalStateException(\"OSS bucket not configured\");","typeGuard":"boolean isOssUploadFailure(BizException e) {\n    return e.getError() != null && \"OSS_UPLOAD_ERROR\".equals(e.getError().getCode());\n}","tryCatchPattern":"try {\n    ossManager.uploadFile(in, path);\n} catch (BizException e) {\n    if (isOssUploadFailure(e) && e.getCause() instanceof OSSException ose) {\n        log.error(\"OSS rejected upload, requestId={}\", ose.getRequestId(), ose);\n    }\n    throw e;\n}","preventionTips":["Verify bucket/endpoint/region config in each environment before deploying","Grant the RAM role oss:PutObject on the target bucket","Prefer fresh, managed input streams (try-with-resources)","Retry transient network failures with exponential backoff"],"tags":["oss","storage","upload"],"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"}