pentaho/pentaho-kettle · error · KettleDatabaseException

Unable to construct a JDBC URL: at least the database name…

Error message

Unable to construct a JDBC URL: at least the database name must be specified

What it means

OracleDatabaseMeta.getURL throws this KettleDatabaseException when the Oracle connection attributes are too incomplete to build any JDBC URL — specifically, no database name (SID/service) is specified. A JDBC URL cannot be formed for the requested access type (OCI/thin) without it.

Solutions

1. Set the database name (SID or service name) in the Oracle connection dialog/database meta before connecting
2. If using a TNS alias via OCI, provide the alias as the database name
3. Switch access method (e.g. to a manual JDBC URL or TNS-based option) that does not require the SID field

Example fix

// before
DatabaseMeta db = new DatabaseMeta("oracle", "Oracle", "Native", "host", "", "1521", "user", "pass");
// after
DatabaseMeta db = new DatabaseMeta("oracle", "Oracle", "Native", "host", "ORCL", "1521", "user", "pass");

if (databaseMeta.getDatabaseName() == null || databaseMeta.getDatabaseName().trim().isEmpty()) {
  throw new IllegalArgumentException("Oracle connection requires a database name (SID or service name)");
}

function hasOracleDatabaseName(DatabaseMeta db) { return db != null && db.getDatabaseName() != null && !db.getDatabaseName().trim().isEmpty(); }

try {
  String url = oracleMeta.getURL(hostname, port, databaseName);
} catch (KettleDatabaseException e) {
  log.error("Oracle JDBC URL could not be built — database name missing", e);
}

When it happens

Trigger: Calling getURL(hostname, port, null-or-empty databaseName, ...) on an Oracle database meta while the selected access method requires a SID/service name (e.g. OCI shortcut form 'jdbc:oracle:oci:@name').

Common situations: Oracle connection settings in a transformation/job leaving the SID/Service field empty; misconfigured repository connection; users assuming the TNS alias is optional for the chosen access type.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• Dynamic driver ' ' does not accept URL: — check the JDBC…
• Cannot fetch driver metadata for
• Dynamic driver ' ' returned null for URL: — check that the…
• Dynamic driver ' ' threw exception checking URL
• Error getting synonyms from schema []

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

Appendix: source

Thrown at core/src/main/java/org/pentaho/di/core/database/OracleDatabaseMeta.java:148

      } else {
        // by default we assume a SID
        return "jdbc:oracle:thin:@" + hostname + ":" + port + ":" + databaseName;
      }
    } else {
      // OCI
      // Let's see if we have an database name
      if ( databaseName != null && databaseName.length() > 0 ) {
        // Has the user specified hostname & port number?
        if ( hostname != null && hostname.length() > 0 && port != null && port.length() > 0 ) {
          // User wants the full url
          return "jdbc:oracle:oci:@(description=(address=(host=" + hostname + ")(protocol=tcp)(port=" + port
              + "))(connect_data=(sid=" + databaseName + ")))";
        } else {
          // User wants the shortcut url
          return "jdbc:oracle:oci:@" + databaseName;
        }
      } else {
        throw new KettleDatabaseException(
            "Unable to construct a JDBC URL: at least the database name must be specified" );
      }
    }
  }

  /**
   * Oracle doesn't support options in the URL, we need to put these in a Properties object at connection time...
   */
  @Override
  public boolean supportsOptionsInURL() {
    return false;
  }

  /**
   * @return true if the database supports sequences
   */
  @Override
  public boolean supportsSequences() {

View on GitHub (pinned to f3058517a1)