{"record":{"id":"e2064b2ecb9a5cb9","repo":"pentaho/pentaho-kettle","slug":"jobentrysetvariables-error-unablereadpropertiesfile","errorCode":null,"errorMessage":"JobEntrySetVariables.Error.UnableReadPropertiesFile","messagePattern":"JobEntrySetVariables\\.Error\\.UnableReadPropertiesFile","errorType":"exception","errorClass":"KettleException","httpStatus":null,"severity":"error","filePath":"engine/src/main/java/org/pentaho/di/job/entries/setvariables/JobEntrySetVariables.java","lineNumber":243,"sourceCode":"      List<String> variableValues = new ArrayList<String>();\n      List<Integer> variableTypes = new ArrayList<Integer>();\n\n      String realFilename = environmentSubstitute( filename );\n      if ( !Utils.isEmpty( realFilename ) ) {\n        try ( InputStream is = KettleVFS.getInstance( parentJobMeta.getBowl() ).getInputStream( realFilename );\n            // for UTF8 properties files\n            InputStreamReader isr = new InputStreamReader( is, \"UTF-8\" );\n            BufferedReader reader = new BufferedReader( isr );\n            ) {\n          Properties properties = new Properties();\n          properties.load( reader );\n          for ( Map.Entry<Object, Object> entry : properties.entrySet() ) {\n            variables.add( (String) entry.getKey() );\n            variableValues.add( (String) entry.getValue() );\n            variableTypes.add( fileVariableType );\n          }\n        } catch ( Exception e ) {\n          throw new KettleException( BaseMessages.getString(\n            PKG, \"JobEntrySetVariables.Error.UnableReadPropertiesFile\", realFilename ) );\n        }\n      }\n\n      if ( variableName != null ) {\n        for ( int i = 0; i < variableName.length; i++ ) {\n          if ( ( variables.contains( variableName[ i ] ) && replaceVars ) || !variables.contains(\n            variableName[ i ] ) ) {\n            variables.add( variableName[ i ] );\n            variableValues.add( variableValue[ i ] );\n            variableTypes.add( variableType[ i ] );\n          }\n        }\n      }\n\n      // if parentJob exists - clear/reset all entrySetVariables before applying the actual ones\n      if ( parentJob != null ) {\n        for ( String key : getEntryStepSetVariablesMap().keySet() ) {","sourceCodeStart":225,"sourceCodeEnd":261,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/job/entries/setvariables/JobEntrySetVariables.java#L225-L261","documentation":"This KettleException is thrown in execute() when reading the properties file that supplies variable names/values fails. The entry loads a .properties file (filename after environment substitution) to define variables; any exception during load is replaced with the localized JobEntrySetVariables.Error.UnableReadPropertiesFile message naming the file. Note the original exception is not chained.","triggerScenarios":"Executing the entry with 'File' variable source where realFilename points to a missing, unreadable, or malformed properties file, or the file cannot be opened by Properties.load (IO error, bad encoding, path is a directory).","commonSituations":"Typo in filename or wrong path on the execution node (file exists only on the dev machine); missing environment variable in the filename path; agent running with a different working directory; properties file with invalid characters/encoding; file permissions.","solutions":["Verify the file exists and is readable at the exact resolved path on the machine running the job (log realFilename)","Check that any variables used in the filename are defined in kettle.properties or passed at runtime","If the filename uses ${Internal.Transformation.Filename.Directory}-style relative paths, confirm the job's location context","Fix encoding/syntax problems in the properties file (ISO-8859-1 expected by Properties.load)"],"exampleFix":"// before\n// Filename field: ${CONFIG_DIR}/app.properties  (CONFIG_DIR unset on server)\n// after\n// define in ~/.kettle/kettle.properties:\nCONFIG_DIR=/opt/pdi/config\n// or use an absolute path: /opt/pdi/config/app.properties","handlingStrategy":"validation","validationCode":"// before running the job, verify the resolved properties file\nString path = job.environmentSubstitute(\"${CONFIG_DIR}/app.properties\");\nFile pf = new File(path);\nif (!pf.isFile() || !pf.canRead()) {\n  throw new IllegalStateException(\"Properties file not readable: \" + path);\n}","typeGuard":null,"tryCatchPattern":"try {\n  result = jobEntry.execute(result, nr);\n} catch (KettleException e) {\n  if (e.getMessage().contains(\"UnableReadPropertiesFile\")) {\n    logError(\"Check properties file path/permissions on the executing node: \" + e.getMessage());\n  }\n}","preventionTips":["Use absolute paths or verify variables in the filename resolve on the execution node","Keep the properties file deployed alongside the job on every agent node","Remember Properties.load expects ISO-8859-1; avoid exotic encodings","Check file permissions for the user running Kitchen"],"tags":["pdi","file-io","configuration"],"backgroundTag":"file-read-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"}