{"record":{"id":"52c8f935705e2710","repo":"pentaho/pentaho-kettle","slug":"repositoryproxy-error-0001-missing-ref","errorCode":"RepositoryProxy.ERROR_0001_MISSING_REF","errorMessage":"RepositoryProxy.ERROR_0001_MISSING_REF","messagePattern":"RepositoryProxy\\.ERROR_0001_MISSING_REF","errorType":"exception","errorClass":"KettleException","httpStatus":null,"severity":"error","filePath":"plugins/pur/core/src/main/java/org/pentaho/di/repository/pur/RepositoryProxy.java","lineNumber":472,"sourceCode":"  private DatabaseMeta loadDatabaseMeta( String code, List<DatabaseMeta> databases ) throws KettleException {\n    DataProperty codeProp = node.getProperty( code );\n    if ( codeProp != null ) {\n      return loadDatabaseMetaFromReference( codeProp, databases );\n    } else {\n      DataProperty nameProp = node.getProperty( code + PROP_CODE_NR_SEPARATOR + NAME_EXT );\n      if ( nameProp != null ) {\n        String dbName = nameProp.getString();\n        return DatabaseMeta.findDatabase( databases, dbName );\n      }\n    }\n    return null;\n  }\n\n  private DatabaseMeta loadDatabaseMetaFromReference( DataProperty codeProp, List<DatabaseMeta> databases )\n    throws KettleException {\n    if ( DataNodeRef.REF_MISSING.equals( codeProp.getRef().getId() )\n        && System.getProperty( \"kettle.allow_missing_refs\" ) == null ) {\n      throw new KettleException( BaseMessages.getString( PKG, \"RepositoryProxy.ERROR_0001_MISSING_REF\" ) );\n    }\n    ObjectId databaseId = new StringObjectId( codeProp.getRef().getId().toString() );\n    DatabaseMeta databaseMeta = DatabaseMeta.findDatabase( databases, databaseId );\n    if ( databaseMeta != null ) {\n      return databaseMeta;\n    }\n    // The referenced ObjectId is not in the current set of DBs. It may have been overridden by another.\n    // Try to find the original DB and load the overriding one by name.\n    DatabaseMeta orig = loadDatabaseMeta( databaseId, null );\n    if ( orig != null ) {\n      DatabaseMeta override = DatabaseMeta.findDatabase( databases, orig.getName() );\n      return override == null ? orig : override;\n    }\n    return null;\n  }\n\n  @Override\n  public DatabaseMeta loadDatabaseMetaFromStepAttribute( ObjectId idStep, String code, List<DatabaseMeta> databases )","sourceCodeStart":454,"sourceCodeEnd":490,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/plugins/pur/core/src/main/java/org/pentaho/di/repository/pur/RepositoryProxy.java#L454-L490","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Re-create the missing database connection in the target repository so the reference resolves.","Re-export/re-save the transformation or job from the source repository after ensuring referenced connections exist.","As a last resort, set -Dkettle.allow_missing_refs=true to allow loading with the missing reference, then fix the connection mapping manually.","Check the ref ID in the stored content and map it to an existing DatabaseMeta."],"exampleFix":"// before\nDatabaseMeta db = proxy.loadDatabaseMeta( node, sharedDatabases ); // throws on missing ref\n// after\n// run JVM with -Dkettle.allow_missing_refs=true, or ensure the connection exists first\nDatabaseMeta missing = DatabaseMeta.findDatabase( sharedDatabases, missingRefId );\nif ( missing == null ) {\n  sharedDatabases.add( recreateConnection( missingRefId ) ); // re-create before loading\n}\nDatabaseMeta db = proxy.loadDatabaseMeta( node, sharedDatabases );","handlingStrategy":"try-catch","validationCode":"String refId = codeProp.getRef().getId().toString();\nboolean connectionExists = DatabaseMeta.findDatabase( databases, new StringObjectId( refId ) ) != null;","typeGuard":null,"tryCatchPattern":"try {\n  DatabaseMeta db = proxy.loadDatabaseMeta( node, databases );\n} catch ( KettleException e ) {\n  logError( \"Missing database reference in \" + node.getName() + \": \" + e.getMessage() );\n  db = promptForReplacementConnection();\n}","preventionTips":["Ensure shared database connections exist before importing transformations","Re-create connections in the target repository when migrating content","Avoid deleting database connections still referenced by jobs/transformations","Use kettle.allow_missing_refs only as a temporary diagnostic"],"tags":["repository","database-connection","broken-reference","pentaho-kettle"],"backgroundTag":"resource-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"}