{"record":{"id":"b261e6f09b80278e","repo":"pentaho/pentaho-kettle","slug":"metainjectmeta-exception-unabletoloadtrans","errorCode":"MetaInjectMeta.Exception.UnableToLoadTrans","errorMessage":"MetaInjectMeta.Exception.UnableToLoadTrans","messagePattern":"MetaInjectMeta\\.Exception\\.UnableToLoadTrans","errorType":"exception","errorClass":"KettleException","httpStatus":null,"severity":"error","filePath":"plugins/meta-inject/impl/src/main/java/org/pentaho/di/trans/steps/metainject/MetaInjectMeta.java","lineNumber":699,"sourceCode":"\n      // Set the correct filename inside the XML.\n      //\n      executorTransMeta.setFilename( newFilename );\n\n      // exports always reside in the root directory, in case we want to turn\n      // this into a file repository...\n      //\n      executorTransMeta.setRepositoryDirectory( new RepositoryDirectory() );\n\n      // change it in the entry\n      //\n      fileName = newFilename;\n\n      setSpecificationMethod( ObjectLocationSpecificationMethod.FILENAME );\n\n      return proposedNewFilename;\n    } catch ( Exception e ) {\n      throw new KettleException( BaseMessages.getString( PKG, \"MetaInjectMeta.Exception.UnableToLoadTrans\",\n        fileName ) );\n    }\n  }\n\n  @Override\n  public boolean excludeFromCopyDistributeVerification() {\n    return true;\n  }\n\n  @Override\n  public boolean excludeFromRowLayoutVerification() {\n    return true;\n  }\n\n  /**\n   * @return the sourceStepName\n   */\n  public String getSourceStepName() {","sourceCodeStart":681,"sourceCodeEnd":717,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/plugins/meta-inject/impl/src/main/java/org/pentaho/di/trans/steps/metainject/MetaInjectMeta.java#L681-L717","documentation":"In MetaInjectMeta's filename-encoding/relocation logic (building a new export filename and switching specification to FILENAME), any exception in the surrounding block is rethrown as a KettleException with localized MetaInjectMeta.Exception.UnableToLoadTrans naming the current fileName. It indicates the step could not resolve/normalize its referenced transformation file.","triggerScenarios":"The load/normalize routine that sets fileName and setSpecificationMethod(FILENAME) hitting an exception — e.g. variable substitution failing, IO errors deriving newFilename, or the referenced file being unreadable.","commonSituations":"Exporting/moving a job whose Meta Inject steps reference files by relative path; missing variables during export; file permissions on the target directory when proposing a new filename.","solutions":["Check the fileName value in the message and confirm that file exists and is readable.","Fix or define the variables used in the filename before running the export/load.","Verify write permissions if a new proposed filename must be created in that directory.","Re-point the Meta Inject step at the transformation file explicitly."],"exampleFix":"// before\nString file = \"${UNDEFINED_VAR}/child.ktr\";\n// after: ensure variable defined or use internal variable\nString file = \"${Internal.Transformation.Filename.Directory}/child.ktr\";","handlingStrategy":"try-catch","validationCode":"// Validate the current fileName resolves before the export/normalize step\nString resolved = space.environmentSubstitute(fileName);\nif (Utils.isEmpty(resolved)) throw new IllegalStateException(\"fileName variable unresolved\");","typeGuard":null,"tryCatchPattern":"try {\n  editFileName();\n} catch (KettleException e) {\n  logError(\"Unable to load trans referenced by \" + fileName + \": \" + e.getMessage(), e);\n}","preventionTips":["Define variables used in filenames before exports","Ensure write permission on the export target directory","Avoid relative paths; anchor to internal directory variables"],"tags":["file-not-found","kettle","meta-inject","export"],"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"}