pentaho/pentaho-kettle · error · KettleException

Unable to load database connection from the file repository

Error message

Unable to load database connection from the file repository

What it means

loadDatabaseMeta(id, versionName) constructs a DatabaseMeta from the XML node loaded by loadNodeFromXML(id, DatabaseMeta.XML_TAG); any exception (node not loadable or constructor parse failure) is wrapped in this fixed-message KettleException. The actual reason is available via getCause().

Solutions

  1. Verify the database connection object exists in the repository (search by name in Spoon)
  2. Recreate the connection in Spoon and re-save if its XML is corrupt
  3. Check getCause() to distinguish missing-file from parse errors
  4. Ensure you are connected to the intended repository/base directory

Example fix

// before
DatabaseMeta db = repository.loadDatabaseMeta(id, null);
// after
DatabaseMeta db;
try {
  db = repository.loadDatabaseMeta(id, null);
} catch (KettleException e) {
  db = DatabaseMeta.findDatabase(sharedDatabases, expectedName);
  if (db == null) throw e;
}
Defensive patterns

Strategy: try-catch

Validate before calling

if (id_database == null) throw new KettleException("Transformation/job references no database connection id");

Try / catch

try {
  DatabaseMeta db = repository.loadDatabaseMeta(id, null);
} catch (KettleException e) {
  DatabaseMeta fallback = DatabaseMeta.findDatabase(availableDatabases, expectedName);
  if (fallback == null) throw new KettleException("Connection missing in repository", e);
  db = fallback;
}

Prevention

When it happens

Trigger: Calling loadDatabaseMeta with an id whose database-connection file is absent, unreadable, or whose XML is not a valid <connection> node parseable by DatabaseMeta.

Common situations: Referenced database connection deleted from the repository; hand-edited or partially saved connection XML; repository directory permissions blocking read; wrong repository opened so the id resolves to nothing.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/repository/filerep/KettleFileRepository.java:913

      //
      String filename = calcDirectoryName( null ) + id.getId();
      FileObject fileObject = KettleVFS.getInstance( DefaultBowl.getInstance() ).getFileObject( filename );
      Document document = XMLHandler.loadXMLFile( fileObject );
      Node node = XMLHandler.getSubNode( document, tag );

      return node;
    } catch ( Exception e ) {
      throw new KettleException( "Unable to load XML object from object with ID ["
        + id + "] and tag [" + tag + "]", e );
    }
  }

  @Override
  public DatabaseMeta loadDatabaseMeta( ObjectId id_database, String versionName ) throws KettleException {
    try {
      return new DatabaseMeta( loadNodeFromXML( id_database, DatabaseMeta.XML_TAG ) );
    } catch ( Exception e ) {
      throw new KettleException( "Unable to load database connection from the file repository", e );
    }
  }

  @Override
  public DatabaseMeta loadDatabaseMetaFromJobEntryAttribute( ObjectId id_jobentry, String nameCode, int nr,
    String idCode, List<DatabaseMeta> databases ) throws KettleException {
    return null;
  }

  @Override
  public void saveDatabaseMetaJobEntryAttribute( ObjectId id_job, ObjectId id_jobentry, int nr, String nameCode,
    String idCode, DatabaseMeta database ) throws KettleException {
  }

  @Override
  public DatabaseMeta loadDatabaseMetaFromStepAttribute( ObjectId id_step, String code,
    List<DatabaseMeta> databases ) throws KettleException {
    return null;

View on GitHub (pinned to f3058517a1)