pentaho/pentaho-kettle · error · KettleException

RepositoryProxy.ERROR_0001_MISSING_REF

RepositoryProxy.ERROR_0001_MISSING_REF

Error message

RepositoryProxy.ERROR_0001_MISSING_REF

What it means

When loading an element (transformation/job) the repository encounters a property that references a database connection by ID, but the reference is marked REF_MISSING. Unless the system property kettle.allow_missing_refs is set, loadDatabaseMeta throws this KettleException because the referenced database metadata cannot be resolved. This guards against silently loading content with broken database references.

Solutions

1. Re-create the missing database connection in the target repository so the reference resolves.
2. Re-export/re-save the transformation or job from the source repository after ensuring referenced connections exist.
3. As a last resort, set -Dkettle.allow_missing_refs=true to allow loading with the missing reference, then fix the connection mapping manually.
4. Check the ref ID in the stored content and map it to an existing DatabaseMeta.

Example fix

// before
DatabaseMeta db = proxy.loadDatabaseMeta( node, sharedDatabases ); // throws on missing ref
// after
// run JVM with -Dkettle.allow_missing_refs=true, or ensure the connection exists first
DatabaseMeta missing = DatabaseMeta.findDatabase( sharedDatabases, missingRefId );
if ( missing == null ) {
  sharedDatabases.add( recreateConnection( missingRefId ) ); // re-create before loading
}
DatabaseMeta db = proxy.loadDatabaseMeta( node, sharedDatabases );

String refId = codeProp.getRef().getId().toString();
boolean connectionExists = DatabaseMeta.findDatabase( databases, new StringObjectId( refId ) ) != null;

try {
  DatabaseMeta db = proxy.loadDatabaseMeta( node, databases );
} catch ( KettleException e ) {
  logError( "Missing database reference in " + node.getName() + ": " + e.getMessage() );
  db = promptForReplacementConnection();
}

When it happens

Trigger: Loading a transformation or job whose stored DataNode contains a database reference whose ID is DataNodeRef.REF_MISSING, via UnifiedRepository/RepositoryProxy.loadDatabaseMeta, and kettle.allow_missing_refs is not set.

Common situations: Content exported from one repository and imported into another where the referenced shared database connection does not exist, deleted database connections still referenced by old transformations, or repository migrations that lost connection definitions.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Could not retrieve version history of object with path
• DELETE_JOB : repository is read-only
• DynamicSQLRowMeta.Exception.UnableToSaveStepInfo
• " + element.getName() + " has a null id
• ERROR_0002_Cannot_Load_Job_From_Repository

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

Appendix: source

Thrown at plugins/pur/core/src/main/java/org/pentaho/di/repository/pur/RepositoryProxy.java:472

  private DatabaseMeta loadDatabaseMeta( String code, List<DatabaseMeta> databases ) throws KettleException {
    DataProperty codeProp = node.getProperty( code );
    if ( codeProp != null ) {
      return loadDatabaseMetaFromReference( codeProp, databases );
    } else {
      DataProperty nameProp = node.getProperty( code + PROP_CODE_NR_SEPARATOR + NAME_EXT );
      if ( nameProp != null ) {
        String dbName = nameProp.getString();
        return DatabaseMeta.findDatabase( databases, dbName );
      }
    }
    return null;
  }

  private DatabaseMeta loadDatabaseMetaFromReference( DataProperty codeProp, List<DatabaseMeta> databases )
    throws KettleException {
    if ( DataNodeRef.REF_MISSING.equals( codeProp.getRef().getId() )
        && System.getProperty( "kettle.allow_missing_refs" ) == null ) {
      throw new KettleException( BaseMessages.getString( PKG, "RepositoryProxy.ERROR_0001_MISSING_REF" ) );
    }
    ObjectId databaseId = new StringObjectId( codeProp.getRef().getId().toString() );
    DatabaseMeta databaseMeta = DatabaseMeta.findDatabase( databases, databaseId );
    if ( databaseMeta != null ) {
      return databaseMeta;
    }
    // The referenced ObjectId is not in the current set of DBs. It may have been overridden by another.
    // Try to find the original DB and load the overriding one by name.
    DatabaseMeta orig = loadDatabaseMeta( databaseId, null );
    if ( orig != null ) {
      DatabaseMeta override = DatabaseMeta.findDatabase( databases, orig.getName() );
      return override == null ? orig : override;
    }
    return null;
  }

  @Override
  public DatabaseMeta loadDatabaseMetaFromStepAttribute( ObjectId idStep, String code, List<DatabaseMeta> databases )

View on GitHub (pinned to f3058517a1)