{"record":{"id":"12c75b10d85f0e68","repo":"pentaho/pentaho-kettle","slug":"stepwithmappingmeta-exception-unabletoloadtrans","errorCode":null,"errorMessage":"StepWithMappingMeta.Exception.UnableToLoadTrans","messagePattern":"StepWithMappingMeta\\.Exception\\.UnableToLoadTrans","errorType":"exception","errorClass":"KettleException","httpStatus":null,"severity":"error","filePath":"engine/src/main/java/org/pentaho/di/base/MetaFileLoaderImpl.java","lineNumber":467,"sourceCode":"          // via parent space.\n          realFilename = space.environmentSubstitute( realFilename );\n        }\n        theMeta = attemptCacheRead( realFilename ); //try to get from the cache first\n        if ( theMeta == null ) {\n          try {\n            // OK, load the meta-data from file...\n            // Don't set internal variables: they belong to the parent thread!\n            if ( rep != null ) {\n              theMeta = getMetaFromRepository2( bowl, realFilename, rep, r, idContainer );\n            }\n            if ( theMeta == null ) {\n              theMeta = attemptLoadMeta( bowl, realFilename, rep, metaStore, null, tmpSpace, idContainer );\n              LogChannel.GENERAL.logDetailed( LOADING + friendlyMetaType + FROM_REPOSITORY,\n                friendlyMetaType + \" was loaded from XML file [\" + realFilename + \"]\" );\n            }\n          } catch ( Exception e ) {\n            if ( isTransMeta() ) {\n              throw new KettleException(\n                BaseMessages.getString( persistentClass, \"StepWithMappingMeta.Exception.UnableToLoadTrans\" ), e );\n            } else {\n              throw new KettleException(\n                BaseMessages.getString( persistentClass, \"JobExecutorMeta.Exception.UnableToLoadJob\" ), e );\n            }\n          }\n        }\n        break;\n\n      case REPOSITORY_BY_NAME:\n        String realMetaName = tmpSpace.environmentSubstitute( Const.NVL( metaName, \"\" ) );\n        String realDirectory = tmpSpace.environmentSubstitute( Const.NVL( directory, \"\" ) );\n\n        if ( isTransMeta() && space != null ) {\n          // This is a parent transformation and parent variable should work here. A child file name can be\n          // resolved via\n          // parent space.\n          realMetaName = space.environmentSubstitute( realMetaName );","sourceCodeStart":449,"sourceCodeEnd":485,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/base/MetaFileLoaderImpl.java#L449-L485","documentation":"Wrapping KettleException thrown by MetaFileLoaderImpl.getMetaForStep: when loading a child transformation (TransMeta branch, e.g. a Mapping or Transformation Executor step) from repository or XML fails with any exception, it is rethrown with the StepWithMappingMeta 'unable to load transformation' message and the original exception as cause. The real failure (parse error, missing file, repository error) is in the cause chain.","triggerScenarios":"specificationMethod=FILENAME with rep==null path via attemptLoadMeta (new TransMeta(...)) throwing — corrupt/unreadable .ktr XML, missing file, incompatible schema — or getMetaFromRepository2/getMetaFromRepository throwing for repository loads; any Exception during these load attempts is wrapped by this message.","commonSituations":"Child transformation file moved/deleted or variable in filename unresolved to a bad path; .ktr saved by a newer PDI version failing to parse; repository directory/object renamed; permission or network problems against the repository; class-not-found for a step plugin used inside the child transformation.","solutions":["Inspect the cause chain (e.getCause()) — fix the underlying load error it names (missing file, repository directory, XML parse).","Verify the child transformation path/file: resolve all ${VARIABLES} in the filename and confirm the .ktr exists and is readable at runtime.","Open the child transformation in Spoon to confirm it parses in the current PDI version; re-save or upgrade/downgrade the plugin producing the error.","If loading from repository, confirm specificationMethod, metaName and directory match an existing repository object (see errors 615-617).","Clear or bypass any stale meta file cache entry (metaFileCache) that may hold a broken reference."],"exampleFix":"// before\nString file = \"${INTERNAL_TRANSFORM_DIR}/child.ktr\"; // variable unset at runtime\nmappingMeta.setFileName(file);\n\n// after\nString file = space.environmentSubstitute(\"${INTERNAL_TRANSFORM_DIR}\") + \"/child.ktr\";\nif (new File(file).canRead()) {\n  mappingMeta.setFileName(file);\n} else {\n  throw new KettleException(\"Child transformation not found: \" + file);\n}","handlingStrategy":"try-catch","validationCode":"// Java caller, before getMetaForStep for FILENAME-based specs\nString real = space.environmentSubstitute(mappingMeta.getFileName());\nif (!(new File(real).canRead())) {\n  throw new IllegalArgumentException(\"Child transformation not readable: \" + real);\n}","typeGuard":null,"tryCatchPattern":"try {\n  T meta = loader.getMetaForStep(bowl, rep, metaStore, space);\n} catch (KettleException e) {\n  if (String.valueOf(e.getMessage()).contains(\"UnableToLoadTrans\")) {\n    log.error(\"Failed to load child transformation\", e.getCause());\n    throw new ConfigurationException(\"Child transformation load failed; cause: \"\n      + (e.getCause() != null ? e.getCause().getMessage() : e.getMessage()), e);\n  }\n  throw e;\n}","preventionTips":["Resolve and verify every ${VARIABLE} in child transformation filenames before running the parent.","Keep child .ktr files in stable, deployed locations alongside the parent (relative paths where possible).","Ensure all step plugins used by child transformations are installed in the runtime's plugin folders.","Check the cause chain first — this error is always a wrapper around the real load failure."],"tags":["kettle","pdi","transformation-load","wrapped-exception"],"backgroundTag":"resource-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"}