{"record":{"id":"2b62cdc5afe01dcf","repo":"pentaho/pentaho-kettle","slug":"error-retrieving-controlfile-string","errorCode":null,"errorMessage":"Error retrieving controlfile string","messagePattern":"Error retrieving controlfile string","errorType":"exception","errorClass":"KettleException","httpStatus":null,"severity":"error","filePath":"plugins/gp-bulk-loader/core/src/main/java/org/pentaho/di/trans/steps/gpbulkloader/GPBulkLoader.java","lineNumber":334,"sourceCode":"        String psqlexec = KettleVFS.getFilename( fileObject );\n        sb.append( enclosure ).append( psqlexec ).append( enclosure );\n      } catch ( Exception ex ) {\n        throw new KettleException( \"Error retrieving sqlldr string\", ex );\n      }\n    } else {\n      throw new KettleException( \"No psql application specified\" );\n    }\n\n    if ( meta.getControlFile() != null ) {\n      try {\n        FileObject fileObject =\n          KettleVFS.getInstance( getTransMeta().getBowl() )\n            .getFileObject( environmentSubstitute( meta.getControlFile() ), getTransMeta() );\n\n        sb.append( \" -n -f \" );\n        sb.append( enclosure ).append( KettleVFS.getFilename( fileObject ) ).append( enclosure );\n      } catch ( Exception ex ) {\n        throw new KettleException( \"Error retrieving controlfile string\", ex );\n      }\n    } else {\n      throw new KettleException( \"No control file specified\" );\n    }\n\n    if ( meta.getLogFile() != null ) {\n      try {\n        FileObject fileObject =\n          KettleVFS.getInstance( getTransMeta().getBowl() )\n            .getFileObject( environmentSubstitute( meta.getLogFile() ), getTransMeta() );\n\n        sb.append( \" -o \" );\n        sb.append( enclosure ).append( KettleVFS.getFilename( fileObject ) ).append( enclosure );\n      } catch ( Exception ex ) {\n        throw new KettleException( \"Error retrieving logfile string\", ex );\n      }\n    }\n","sourceCodeStart":316,"sourceCodeEnd":352,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/plugins/gp-bulk-loader/core/src/main/java/org/pentaho/di/trans/steps/gpbulkloader/GPBulkLoader.java#L316-L352","documentation":"After appending the psql executable, createCommandLine() resolves meta.getControlFile() through environmentSubstitute() and KettleVFS to append '-n -f <controlfile>' to the psql command. Any exception during that resolution is wrapped in this KettleException. The real cause (VFS error, bad path, unresolved variable) is attached as the cause.","triggerScenarios":"createCommandLine() runs with meta.getControlFile() non-null, but KettleVFS.getFileObject(environmentSubstitute(controlFile)) throws: unknown VFS scheme, IO error resolving the file, or an unresolvable variable inside the control file path.","commonSituations":"Control file path references a variable not defined in kettle.properties or transformation parameters; control file lives on a remote VFS mount whose provider is missing; the control file was deleted/moved after the transformation was saved; Windows path with backslashes misinterpreted by VFS.","solutions":["Check ex.getCause() to see the actual VFS/resolution error and fix that root problem.","Resolve all variables in the control file path (define them in kettle.properties or as transformation parameters).","Verify the control file exists at the given path on the machine running Kettle (not just where psql will run).","Use forward slashes / a supported VFS URI (file:///...) if the path contains Windows backslashes."],"exampleFix":"// before\nControl file: ${GP_CTL}/load.ctl   (GP_CTL undefined -> VFS/variable resolution throws)\n\n// after: define the variable or hardcode a verified path\nkettle.properties: GP_CTL=/opt/gp/control\nControl file: ${GP_CTL}/load.ctl","handlingStrategy":"validation","validationCode":"String ctl = meta.getControlFile();\nif (ctl == null || ctl.trim().isEmpty())\n  throw new IllegalArgumentException(\"Control file not set\");\nString resolved = transformation.environmentSubstitute(ctl);\nif (resolved.contains(\"${\"))\n  throw new IllegalArgumentException(\"Unresolved variable in control file path: \" + ctl);\nif (!new java.io.File(resolved).canRead())\n  throw new IllegalArgumentException(\"Control file not readable: \" + resolved);","typeGuard":null,"tryCatchPattern":"try {\n  execute(meta, wait);\n} catch (KettleException e) {\n  if (e.getMessage().contains(\"Error retrieving controlfile string\")) {\n    logError(\"Control file resolution failed\", e.getCause());\n  } else throw e;\n}","preventionTips":["Verify the control file exists on the Kettle host before running","Resolve variables at the transformation parameter level, not ad hoc","Use forward-slash paths to avoid VFS backslash issues on Windows"],"tags":["vfs","control-file","environment-variable","kettle"],"backgroundTag":"file-not-found","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"}