{"record":{"id":"d9407e37abdfc129","repo":"pentaho/pentaho-kettle","slug":"unable-to-find-native-plugins-definition-file-xmlfile","errorCode":null,"errorMessage":"Unable to find native plugins definition file: ${xmlFile}","messagePattern":"Unable to find native plugins definition file: (.+?)","errorType":"exception","errorClass":"KettlePluginException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/pentaho/di/core/plugins/BasePluginType.java","lineNumber":223,"sourceCode":"      inputStream = getResAsStreamExternal( xmlFile );\n      if ( inputStream == null ) {\n        inputStream = getResAsStreamExternal( \"/\" + xmlFile );\n      }\n\n      if ( !Utils.isEmpty( getAlternativePluginFile() ) && inputStream == null && !Utils.isEmpty( alternative ) ) {\n        // Retry to load a regular file...\n        try {\n          inputStream = getFileInputStreamExternal( xmlFile );\n        } catch ( Exception e ) {\n          throw new KettlePluginException( \"Unable to load native plugins '\" + xmlFile + \"'\", e );\n        }\n      }\n\n      if ( inputStream == null ) {\n        if ( isReturn() ) {\n          return;\n        } else {\n          throw new KettlePluginException( \"Unable to find native plugins definition file: \" + xmlFile );\n        }\n      }\n\n      registerPlugins( inputStream );\n\n    } catch ( KettleXMLException e ) {\n      throw new KettlePluginException( \"Unable to read the kettle XML config file: \" + xmlFile, e );\n    } finally {\n      IOUtils.closeQuietly( inputStream );\n    }\n  }\n\n  @VisibleForTesting\n  protected String getPropertyExternal( String key, String def ) {\n    return System.getProperty( key, def );\n  }\n\n  @VisibleForTesting","sourceCodeStart":205,"sourceCodeEnd":241,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/core/src/main/java/org/pentaho/di/core/plugins/BasePluginType.java#L205-L241","documentation":"After attempting to load the native plugin definition XML from the classpath, registerNatives checks whether it obtained an input stream. If it is still null — the resource was never found — and the plugin type is not marked 'return quietly' (isReturn() false), KettlePluginException 'Unable to find native plugins definition file' is thrown. The plugin type cannot enumerate any native plugins.","triggerScenarios":"searchPlugins() -> registerNatives() where the XML resource for the plugin type does not exist on the classpath (resource name changed, jar missing) and the type doesn't tolerate absence.","commonSituations":"Building a minimal/shaded classpath that excluded plugin descriptor XMLs; relocating/renaming packages so resource lookups miss; custom plugin type whose XML filename doesn't match; removing jars from lib/ that carry the descriptors.","solutions":["Ensure the jar containing the native plugin XML (e.g. kettle-core for standard types) is on the classpath.","Verify the resource path/name expected by the plugin type matches what is packaged (check the plugin type's constructor).","If the plugin type genuinely has no native XML, call setReturn(true) so absence is tolerated.","Check packaging config (maven-shade/assembly) isn't filtering out *.xml descriptors."],"exampleFix":"// before\n<artifactSet><excludes><exclude>org.pentaho.di:*</exclude></excludes></artifactSet>\n// after\n<!-- keep kettle-core so native plugin XMLs stay on classpath -->","handlingStrategy":"validation","validationCode":"String res = \"org/pentaho/di/core/steps/type-list.xml\"; // per plugin type\nif (getClass().getClassLoader().getResource(res) == null) {\n  throw new IllegalStateException(\"Native plugin definition missing from classpath: \" + res);\n}","typeGuard":"static boolean hasPluginDescriptor(String resource) {\n  return Thread.currentThread().getContextClassLoader().getResource(resource) != null;\n}","tryCatchPattern":"try {\n  pluginType.searchPlugins();\n} catch (KettlePluginException e) {\n  log.logError(\"Native plugin definition not found: \" + xmlFile, e);\n}","preventionTips":["Never exclude descriptor XMLs when packaging/minimizing the classpath.","Verify jar contents (jar tf) include the plugin type's native XML.","For optional plugin types, use the return-quietly mode if supported.","Keep full, unmodified Pentaho installation directories."],"tags":["kettle","plugins","classpath","resource-not-found"],"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"}