{"record":{"id":"8b5ebf4aea9b489d","repo":"pentaho/pentaho-kettle","slug":"vfs-provider-local-create-folder-error","errorCode":"vfs.provider.local/create-folder.error","errorMessage":"vfs.provider.local/create-folder.error","messagePattern":"vfs\\.provider\\.local/create-folder\\.error","errorType":"error_code","errorClass":"FileSystemException","httpStatus":null,"severity":"error","filePath":"plugins/s3-vfs/core/src/main/java/org/pentaho/s3common/S3CommonFileObject.java","lineNumber":510,"sourceCode":"  @Override\n  protected void doCreateFolder() throws Exception {\n    if ( !isRootBucket() ) {\n      // create meta-data for your folder and set content-length to 0\n      ObjectMetadata metadata = new ObjectMetadata();\n      metadata.setContentLength( 0 );\n      metadata.setContentType( \"binary/octet-stream\" );\n\n      // create empty content\n      InputStream emptyContent = new ByteArrayInputStream( new byte[ 0 ] );\n\n      // create a PutObjectRequest passing the folder name suffixed by /\n      PutObjectRequest putObjectRequest = createPutObjectRequest( bucketName, key + DELIMITER, emptyContent, metadata );\n\n      // send request to S3 to create folder\n      try {\n        fileSystem.getS3Client().putObject( putObjectRequest );\n      } catch ( AmazonS3Exception e ) {\n        throw new FileSystemException( \"vfs.provider.local/create-folder.error\", this, e );\n      }\n    } else {\n      throw new FileSystemException( \"vfs.provider/create-folder-not-supported.error\" );\n    }\n  }\n\n\n  protected PutObjectRequest createPutObjectRequest( String bucketName, String key, InputStream inputStream,\n                                                     ObjectMetadata objectMetadata ) {\n    return new PutObjectRequest( bucketName, key, inputStream, objectMetadata );\n  }\n\n  @Override\n  protected void doRename( FileObject newFile ) throws Exception {\n    // no folder renames on S3\n    if ( getType().equals( FileType.FOLDER ) ) {\n      logger.debug( \"recursively moving folder [{}] -> [{}]\", this.getPublicURIString(), newFile.getPublicURIString() );\n      doFolderMove( this, newFile );","sourceCodeStart":492,"sourceCodeEnd":528,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/plugins/s3-vfs/core/src/main/java/org/pentaho/s3common/S3CommonFileObject.java#L492-L528","documentation":"Thrown by S3CommonFileObject.doCreateFolder() when the S3 putObject call that creates a zero-byte folder-marker object (key ending with '/') fails with an AmazonS3Exception. VFS folders in S3 are emulated, so folder creation is really an S3 object PUT; any S3-side rejection surfaces as this FileSystemException.","triggerScenarios":"Calling createFolder() on an S3 VFS file object when putObject on the '<key>/' placeholder object returns an AmazonS3Exception (e.g. access denied, no such bucket, throttling).","commonSituations":"IAM policy missing s3:PutObject; typo'd or deleted bucket name; bucket in a region the client is misconfigured for; S3 rate limiting; KMS key not permitted for the caller.","solutions":["Check the wrapped AmazonS3Exception message/error code for the real cause (AccessDenied, NoSuchBucket, etc.)","Verify the AWS credentials/IAM policy allow s3:PutObject on the target bucket/key prefix","Confirm the bucket exists and the region/endpoint in the VFS config matches the bucket's actual region","Retry with backoff if the code is SlowDown/throttling"],"exampleFix":"// before\nfileSystem.getS3Client().putObject( putObjectRequest );\n// after\ntry {\n  fileSystem.getS3Client().putObject( putObjectRequest );\n} catch ( AmazonS3Exception e ) {\n  if ( \"SlowDown\".equals( e.getErrorCode() ) ) { /* retry with backoff */ }\n  throw new FileSystemException( \"vfs.provider.local/create-folder.error\", this, e );\n}","handlingStrategy":"try-catch","validationCode":"// before creating\nFileObject f = fsManager.resolveFile( \"s3://bucket/prefix/\" );\nif ( f.exists() ) { return; } // already there\n// preflight: creds + bucket\ns3Client.getObjectMetadata( bucketName, probeKey ); // throws if bucket/creds bad","typeGuard":"boolean isS3FolderCreatable( FileObject f ) {\n  return f instanceof S3CommonFileObject && f.getName().getDepth() > 0;\n}","tryCatchPattern":"try {\n  fileObject.createFolder();\n} catch ( FileSystemException e ) {\n  Throwable cause = e.getCause();\n  if ( cause instanceof AmazonS3Exception && \"AccessDenied\".equals( ((AmazonS3Exception) cause).getErrorCode() ) ) {\n    // handle permissions problem\n  }\n  throw e;\n}","preventionTips":["Grant s3:PutObject on the target bucket/prefix to the runtime IAM role","Validate bucket existence and region at startup with a lightweight head-bucket call","Handle SlowDown responses with exponential backoff","Prefer writing objects under a prefix over explicit folder creation where possible"],"tags":["s3","vfs","folder-creation","aws"],"backgroundTag":"file-write-failed","analyzedSha":"f3058517a153da500bf4551f46d79b91bf8ec552","analyzedAt":"2026-09-13T14:04:16.340Z","contentChangedAt":"2026-09-13T14:04:16.340Z","schemaVersion":2},"datasetVersion":"2026-09-20T23:17:15.980Z"}