pentaho/pentaho-kettle · error · KettleException

Unable to load file

Error message

Unable to load file {STEP_ATTRIBUTES_FILE}

What it means

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.

Solutions

  1. Verify STEP_ATTRIBUTES_FILE exists on the classpath at the expected package location.
  2. Validate the attributes file's JSON/XML syntax with a linter and fix malformed content.
  3. Rebuild the jar ensuring resource files are not filtered out by build excludes.
  4. Inspect the wrapped cause 'e' for the exact parse or IO failure.

Example fix

// before (resource excluded in pom.xml)
<exclude>**/*.json</exclude>
// after
<exclude>**/tmp/*.json</exclude>
Defensive patterns

Strategy: try-catch

Validate before calling

// Before initializing step metas, verify the resource loads
try (InputStream in = BaseStepMeta.class.getResourceAsStream("/org/pentaho/di/trans/step/step-attributes.json")) {
  if (in == null) throw new IllegalStateException("STEP_ATTRIBUTES_FILE missing from classpath");
}

Try / catch

try { meta.loadStepAttributes(); } catch (KettleException e) { log.error("Attributes file failed to load: " + e.getCause(), e); throw e; }

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "Config file not found": what it means and how to fix it in docker-sync, Maven, Vagrant, Turborepo and other tools — this error's family across 60 libraries.

Related errors

AI-assisted analysis of pentaho/pentaho-kettle@f3058517a1 (2026-09-13). Data as JSON: /api/errors/25721bf7f70cc471. Report an issue: GitHub.

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/step/BaseStepMeta.java:965

        Node attrsNode = XMLHandler.getSubNode( document, "attributes" );
        List<Node> nodes = XMLHandler.getNodes( attrsNode, "attribute" );
        attributes = new ArrayList<KettleAttributeInterface>();
        for ( Node node : nodes ) {
          String key = XMLHandler.getTagAttribute( node, "id" );
          String xmlCode = XMLHandler.getTagValue( node, "xmlcode" );
          String repCode = XMLHandler.getTagValue( node, "repcode" );
          String description = XMLHandler.getTagValue( node, "description" );
          String tooltip = XMLHandler.getTagValue( node, "tooltip" );
          int valueType = ValueMetaFactory.getIdForValueMeta( XMLHandler.getTagValue( node, "valuetype" ) );
          String parentId = XMLHandler.getTagValue( node, "parentid" );

          KettleAttribute attribute = new KettleAttribute( key, xmlCode, repCode, description, tooltip, valueType,
            findParent( attributes, parentId ) );
          attributes.add( attribute );
        }
      }
    } catch ( Exception e ) {
      throw new KettleException( "Unable to load file " + STEP_ATTRIBUTES_FILE, e );
    }
  }

  /*
   * (non-Javadoc)
   *
   * @see org.pentaho.di.trans.step.StepAttributesInterface#findParent(java.util.List, java.lang.String)
   */
  @Override
  public KettleAttributeInterface findParent( List<KettleAttributeInterface> attributes, String parentId ) {
    if ( Utils.isEmpty( parentId ) ) {
      return null;
    }
    for ( KettleAttributeInterface attribute : attributes ) {
      if ( attribute.getKey().equals( parentId ) ) {
        return attribute;
      }
    }

View on GitHub (pinned to f3058517a1)