{"record":{"id":"25721bf7f70cc471","repo":"pentaho/pentaho-kettle","slug":"unable-to-load-file-step-attributes-file","errorCode":null,"errorMessage":"Unable to load file {STEP_ATTRIBUTES_FILE}","messagePattern":"Unable to load file (.+?)","errorType":"exception","errorClass":"KettleException","httpStatus":null,"severity":"error","filePath":"engine/src/main/java/org/pentaho/di/trans/step/BaseStepMeta.java","lineNumber":965,"sourceCode":"        Node attrsNode = XMLHandler.getSubNode( document, \"attributes\" );\n        List<Node> nodes = XMLHandler.getNodes( attrsNode, \"attribute\" );\n        attributes = new ArrayList<KettleAttributeInterface>();\n        for ( Node node : nodes ) {\n          String key = XMLHandler.getTagAttribute( node, \"id\" );\n          String xmlCode = XMLHandler.getTagValue( node, \"xmlcode\" );\n          String repCode = XMLHandler.getTagValue( node, \"repcode\" );\n          String description = XMLHandler.getTagValue( node, \"description\" );\n          String tooltip = XMLHandler.getTagValue( node, \"tooltip\" );\n          int valueType = ValueMetaFactory.getIdForValueMeta( XMLHandler.getTagValue( node, \"valuetype\" ) );\n          String parentId = XMLHandler.getTagValue( node, \"parentid\" );\n\n          KettleAttribute attribute = new KettleAttribute( key, xmlCode, repCode, description, tooltip, valueType,\n            findParent( attributes, parentId ) );\n          attributes.add( attribute );\n        }\n      }\n    } catch ( Exception e ) {\n      throw new KettleException( \"Unable to load file \" + STEP_ATTRIBUTES_FILE, e );\n    }\n  }\n\n  /*\n   * (non-Javadoc)\n   *\n   * @see org.pentaho.di.trans.step.StepAttributesInterface#findParent(java.util.List, java.lang.String)\n   */\n  @Override\n  public KettleAttributeInterface findParent( List<KettleAttributeInterface> attributes, String parentId ) {\n    if ( Utils.isEmpty( parentId ) ) {\n      return null;\n    }\n    for ( KettleAttributeInterface attribute : attributes ) {\n      if ( attribute.getKey().equals( parentId ) ) {\n        return attribute;\n      }\n    }","sourceCodeStart":947,"sourceCodeEnd":983,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/step/BaseStepMeta.java#L947-L983","documentation":"Thrown from BaseStepMeta.loadStepAttributes when the step attributes definition file (STEP_ATTRIBUTES_FILE, typically a JSON resource describing KettleAttribute metadata) fails to load or parse. It wraps the underlying exception in a KettleException because step metadata injection requires this definition.","triggerScenarios":"BaseStepMeta initialization/static loading of STEP_ATTRIBUTES_FILE when the resource is missing from the classpath, unreadable, or contains malformed JSON/XML that the parser rejects.","commonSituations":"A shaded/fat jar that excludes the attributes resource file, a custom step plugin shipping without its step-attributes JSON, or a malformed hand-edited attributes file.","solutions":["Verify STEP_ATTRIBUTES_FILE exists on the classpath at the expected package location.","Validate the attributes file's JSON/XML syntax with a linter and fix malformed content.","Rebuild the jar ensuring resource files are not filtered out by build excludes.","Inspect the wrapped cause 'e' for the exact parse or IO failure."],"exampleFix":"// before (resource excluded in pom.xml)\n<exclude>**/*.json</exclude>\n// after\n<exclude>**/tmp/*.json</exclude>","handlingStrategy":"try-catch","validationCode":"// Before initializing step metas, verify the resource loads\ntry (InputStream in = BaseStepMeta.class.getResourceAsStream(\"/org/pentaho/di/trans/step/step-attributes.json\")) {\n  if (in == null) throw new IllegalStateException(\"STEP_ATTRIBUTES_FILE missing from classpath\");\n}","typeGuard":null,"tryCatchPattern":"try { meta.loadStepAttributes(); } catch (KettleException e) { log.error(\"Attributes file failed to load: \" + e.getCause(), e); throw e; }","preventionTips":["Ship the attributes resource in the plugin jar (check build excludes)","Validate the attributes JSON in CI before publishing the jar","Always log the wrapped cause to identify parse vs IO failure"],"tags":["kettle","resource-loading","file-not-found","classpath"],"backgroundTag":"config-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"}