pentaho/pentaho-kettle · error · KettleException

ERROR_0016_COULD_NOT_GET_REPOSITORY_INSTANCE

ERROR_0016_COULD_NOT_GET_REPOSITORY_INSTANCE

Error message

RepositoryConnectionUtils.ERROR_0016_COULD_NOT_GET_REPOSITORY_INSTANCE

What it means

connectToRepository instantiates the repository implementation via PluginRegistry.loadClass(RepositoryPluginType, repositoryMeta.getId(), Repository.class) and calls repository.init(repositoryMeta). Any failure — plugin missing, class loading error, or init exception — becomes a KettleException with ERROR_0016_COULD_NOT_GET_REPOSITORY_INSTANCE.

Solutions

1. Check the cause chain for ClassNotFoundException/PluginNotFoundException and verify the repository plugin id in repositories.xml matches an installed plugin.
2. Ensure the plugin jar (e.g. for database repositories it's built-in; for others the plugin directory) is present and complete.
3. Upgrade/downgrade so the plugin id matches your Pentaho version, and regenerate repositories.xml entries.
4. Test plugin resolution directly: PluginRegistry.getInstance().loadClass(RepositoryPluginType.class, id, Repository.class) to isolate the failure.
5. Validate RepositoryMeta contents (id, connection settings) before init, since init() failures also land here.

Example fix

// before: failing because custom plugin id missing on server
Repository rep = RepositoryConnectionUtils.connectToRepository(log, null, "MyCustomRepo", u, p, null, false);
// after: verify the plugin exists first
RepositoryMeta rm = ...;
boolean ok = PluginRegistry.getInstance().getPlugins(RepositoryPluginType.class).stream()
    .anyMatch(p -> p.getIds()[0].equals(rm.getId()));
if (!ok) throw new IllegalStateException("Repository plugin not installed: " + rm.getId());
Repository rep = RepositoryConnectionUtils.connectToRepository(log, null, "MyCustomRepo", u, p, null, false);

boolean pluginInstalled = PluginRegistry.getInstance().getPlugins(RepositoryPluginType.class).stream()
    .anyMatch(p -> p.getIds()[0].equals(repositoryMeta.getId()));
if (!pluginInstalled) throw new IllegalStateException("Repository plugin not installed: " + repositoryMeta.getId());

try { rep = RepositoryConnectionUtils.connectToRepository(...); } catch (KettleException e) { if (e.getMessage().contains("ERROR_0016")) { log.error("Repository plugin load/init failed; check plugins dir and cause", e); } throw e; }

When it happens

Trigger: repositoryMeta.getId() references a repository plugin type not registered/installed (e.g. KettleDatabaseRepository vs a custom plugin), plugin jars missing from the classpath/plugins dir, or repository.init() throwing for bad RepositoryMeta settings.

Common situations: Custom repository plugin removed or not deployed on the server; version mismatch where the repositories.xml references a plugin id dropped in a newer Pentaho release; incomplete plugin folder after upgrade; classloader issues in embedded/OSGi environments.

Related errors

• ScriptMeta.Exception.UnableToLoadAdditionalClass
• ScriptMeta.Exception.UnableToParseXMLforAdditionalClasses
• ERROR_0004_REPOSITORY_NOT_FOUND
• ERROR_0018_META_REPOSITORY_NOT_POPULATED
• KafkaConsumerInputMeta.UnableToCreateValueType

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/repository/RepositoryConnectionUtils.java:122

      if ( logger.isDebugEnabled() && logBuffer != null ) {
        logger.debug( logBuffer.getBuffer().toString() );
      }
      throw new KettleException( BaseMessages.getString( PKG,
        "RepositoryConnectionUtils.ERROR_0004_REPOSITORY_NOT_FOUND", repositoryName ) ); //$NON-NLS-1$
    }

    if ( logger.isDebugEnabled() ) {
      logger.debug( " Getting repository instance " ); //$NON-NLS-1$
    }
    Repository repository = null;
    try {
      repository =
        PluginRegistry.getInstance().loadClass( RepositoryPluginType.class, repositoryMeta.getId(),
          Repository.class );
      repository.init( repositoryMeta );

    } catch ( Exception e ) {
      throw new KettleException( BaseMessages.getString(
        "RepositoryConnectionUtils.ERROR_0016_COULD_NOT_GET_REPOSITORY_INSTANCE" ), e ); // $NON-NLS-1$
    }

    // OK, now try the username and password
    if ( logger.isDebugEnabled() ) {
      logger.debug( "Connecting to repository " );
    }

    // Two scenarios here: internal to server or external to server. If internal, you are already authenticated. If
    // external, you must provide a username and additionally specify that the IP address of the machine running this
    // code is trusted.
    repository.connect( userName, "ignore" );

    // OK, the repository is open and ready to use.
    if ( logger.isDebugEnabled() ) {
      logger.debug( " Connected to repository " );
    }

View on GitHub (pinned to f3058517a1)