{"record":{"id":"8db853c86beb9322","repo":"pentaho/pentaho-kettle","slug":"s3fileoutput-error-s3clientinitfailed","errorCode":null,"errorMessage":"S3FileOutput.Error.S3ClientInitFailed","messagePattern":"S3FileOutput\\.Error\\.S3ClientInitFailed","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"plugins/s3-vfs/core/src/main/java/org/pentaho/amazon/s3/S3FileOutputHelper.java","lineNumber":295,"sourceCode":"    } catch ( Exception e ) {\n      response.put( ERROR,\n          BaseMessages.getString( PKG, \"S3FileOutput.Error.ListObjectsFailed\" ) );\n      response.put( ACTION_STATUS, FAILURE_RESPONSE );\n    }\n    return response;\n  }\n\n  public void processS3Path( TransMeta transMeta,\n                             Map<String, String> queryParams,\n                             String path,\n                             JSONArray contents ) throws KettleException {\n    String s3Prefix = S3FileProvider.SCHEME + \"://\";\n    S3Details s3Details = createS3DetailsFromParams( transMeta, queryParams );\n    s3Details.setSpace( new Variables() );\n    s3Details = s3Provider.prepare( s3Details );\n    AmazonS3 s3Client = s3Provider.getS3Client( s3Details );\n    if ( s3Client == null ) {\n      throw new IllegalStateException(\n          BaseMessages.getString( PKG, \"S3FileOutput.Error.S3ClientInitFailed\" )\n      );\n    }\n    String cleanPath = path.replace( s3Prefix, \"\" );\n    String bucketName = cleanPath.contains( S3FileName.DELIMITER )\n        ? cleanPath.substring( 0, cleanPath.indexOf( S3FileName.DELIMITER ) )\n        : cleanPath;\n    String prefix = cleanPath.contains( S3FileName.DELIMITER )\n        ? cleanPath.substring( cleanPath.indexOf( S3FileName.DELIMITER ) + 1 )\n        : \"\";\n    if ( !prefix.isEmpty() && !prefix.endsWith( S3FileName.DELIMITER ) ) {\n      prefix += S3FileName.DELIMITER;\n    }\n\n    ListObjectsV2Request listRequest = new ListObjectsV2Request()\n        .withBucketName( bucketName )\n        .withPrefix( prefix )\n        .withDelimiter( S3FileName.DELIMITER );","sourceCodeStart":277,"sourceCodeEnd":313,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/plugins/s3-vfs/core/src/main/java/org/pentaho/amazon/s3/S3FileOutputHelper.java#L277-L313","documentation":"processS3Path throws IllegalStateException with message key 'S3FileOutput.Error.S3ClientInitFailed' when the S3 provider returns a null AmazonS3 client after prepare(). A null client means the AWS SDK client could not be constructed, typically because credentials or region configuration are missing/invalid.","triggerScenarios":"listS3ContentsAction or testProcessS3PathSuccess -> processS3Path where createS3DetailsFromParams yields credentials (access key/secret) that s3Provider.prepare()/getS3Client() reject, so getS3Client returns null instead of a client.","commonSituations":"Empty or malformed AWS access/secret keys in the step dialog; environment without AWS credentials and no keys configured; wrong region name; IAM profile not available on the host; AWS SDK configuration changes across plugin versions.","solutions":["Set valid AWS access key and secret key in the S3 File Output step (or fix the credentials source: env vars, profile, IAM role).","Verify the AWS region is configured and correct for the bucket.","Check that s3Provider.prepare() gets complete S3Details (bucket, path, credentials, variables resolved) before requesting the client.","Test credentials with AWS CLI (aws sts get-caller-identity) on the same host to rule out environment issues."],"exampleFix":"// before\nAmazonS3 s3Client = s3Provider.getS3Client( s3Details );\nif ( s3Client == null ) {\n  throw new IllegalStateException( BaseMessages.getString( PKG, \"S3FileOutput.Error.S3ClientInitFailed\" ) );\n}\n// after: fail fast with a clearer message when credentials are absent\nif ( s3Details.getAccessKey() == null || s3Details.getSecretKey() == null ) {\n  throw new IllegalStateException( \"AWS credentials are not configured for the S3 File Output step\" );\n}\nAmazonS3 s3Client = s3Provider.getS3Client( s3Details );","handlingStrategy":"validation","validationCode":"// verify credentials before invoking processS3Path\nboolean credsReady = awsAccessKey != null && !awsAccessKey.isEmpty()\n  && awsSecretKey != null && !awsSecretKey.isEmpty();\nif ( !credsReady ) throw new IllegalStateException( \"Configure AWS access/secret keys before running\" );","typeGuard":null,"tryCatchPattern":"try {\n  helper.processS3Path( transMeta, params, path );\n} catch ( IllegalStateException e ) {\n  logError( \"S3 client init failed: \" + e.getMessage() );\n}","preventionTips":["Configure AWS keys or a valid credential chain (env, profile, IAM role)","Set the correct AWS region","Run aws sts get-caller-identity to verify host credentials","Re-test the connection from the step dialog after changes"],"tags":["aws","s3","credentials"],"backgroundTag":"missing-credentials","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"}