{"record":{"id":"aa46a93e0ea460c2","repo":"apache/flink","slug":"failed-to-put-object-for-key","errorCode":null,"errorMessage":"Failed to put object for key: {}","messagePattern":"Failed to put object for key: (.+?)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"flink-filesystems/flink-s3-fs-native/src/main/java/org/apache/flink/fs/s3native/writer/NativeS3ObjectOperations.java","lineNumber":222,"sourceCode":"                    e);\n        }\n    }\n\n    public PutObjectResult putObject(String key, File inputFile) throws IOException {\n        if (useAsyncOperations && transferManager != null) {\n            return putObjectViaTransferManager(key, inputFile);\n        }\n\n        try {\n            PutObjectRequest.Builder requestBuilder =\n                    PutObjectRequest.builder().bucket(bucketName).key(key);\n            applyEncryption(requestBuilder);\n\n            PutObjectResponse response =\n                    s3Client.putObject(requestBuilder.build(), RequestBody.fromFile(inputFile));\n            return new PutObjectResult(response.eTag());\n        } catch (S3Exception e) {\n            throw new IOException(\"Failed to put object for key: \" + key, e);\n        }\n    }\n\n    /**\n     * Uploads an object using the S3TransferManager for better throughput.\n     *\n     * <p>The transfer manager provides optimizations over the basic S3 client:\n     *\n     * <ul>\n     *   <li>Automatic multipart upload handling for large files\n     *   <li>Optimized part sizes and parallelism\n     *   <li>Better memory management through streaming\n     * </ul>\n     *\n     * <p>This method blocks until the upload completes.\n     */\n    private PutObjectResult putObjectViaTransferManager(String key, File inputFile)\n            throws IOException {","sourceCodeStart":204,"sourceCodeEnd":240,"githubUrl":"https://github.com/apache/flink/blob/2f3c205e9266cb30240eb7f4fdab15cad629a70f/flink-filesystems/flink-s3-fs-native/src/main/java/org/apache/flink/fs/s3native/writer/NativeS3ObjectOperations.java#L204-L240","documentation":"putObject() is the single-request upload path used for smaller files (or when the TransferManager is disabled): it PUTs the local file with bucket, key and encryption headers. Any S3Exception from the service is wrapped in this IOException with the key. Unlike the multipart paths there is no uploadId involved; failure is atomic — either the object was written or nothing was.","triggerScenarios":"IAM principal lacking s3:PutObject on the prefix; bucket missing or wrong endpoint; SSE-KMS key unusable by the role (kms:GenerateDataKey); object-lock/WORM bucket rejecting non-conforming headers; size exceeding single-PUT limits (~5GB) when the TransferManager path is disabled; expired credentials.","commonSituations":"Small in-progress part files or metadata objects written via putObject during commits; restrictive bucket policies added after jobs were running; encryption enabled between deploys without KMS grants; MinIO with path-style not set so the bucket is parsed as a hostname.","solutions":["Inspect the wrapped S3Exception code: 403 -> grant s3:PutObject (and kms:* if SSE-KMS); 404/301 -> fix bucket/endpoint/region/path-style.","Reproduce with the same credentials: aws s3api put-object --bucket B --key test --body file.","If files can exceed ~5GB, ensure the async/TransferManager path is enabled so it multiparts automatically (useAsyncOperations + transferManager).","For MinIO/compatible stores set fs.s3.endpoint + fs.s3.path.style.access: true + s3.region."],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"catch (IOException e) { S3Exception s3 = (S3Exception) e.getCause(); if (s3.statusCode() >= 500 || \"SlowDown\".equals(s3.awsErrorDetails().errorCode())) retryWithBackoff(); else surfaceIamOrConfigError(s3); }","preventionTips":["Keep single-PUT objects under ~1GB and let the TransferManager multipart larger files.","Verify endpoint/path-style/region once in staging; most non-transient putObject failures are config or IAM.","Encrypt-aware: whenever you turn on SSE, re-test plain putObject permission including the KMS actions."],"tags":["s3","upload","iam","permissions","configuration","flink"],"backgroundTag":null,"analyzedSha":"2f3c205e9266cb30240eb7f4fdab15cad629a70f","analyzedAt":"2026-08-14T08:48:24.518Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}