apache/iceberg · error · RuntimeException

Failed to list databases

Error message

Failed to list databases

What it means

JdbcSnowflakeClient.listDatabases runs 'SHOW DATABASES IN ACCOUNT' through the JDBC connection pool and translates any resulting SQLException into an IcebergException with the message 'Failed to list databases' via snowflakeExceptionToIcebergException. It means the Snowflake query itself failed - the server returned an error, the connection dropped, credentials/role lacked privileges, or the account was unreachable. Interruption during the call is reported separately as UncheckedInterruptedException.

Source

Thrown at snowflake/src/main/java/org/apache/iceberg/snowflake/JdbcSnowflakeClient.java:222

    } catch (InterruptedException e) {
      throw new UncheckedInterruptedException(
          e, "Interrupted while checking if schema '%s' exists", schema);
    }

    return true;
  }

  @Override
  public List<SnowflakeIdentifier> listDatabases() {
    List<SnowflakeIdentifier> databases;
    try {
      databases =
          connectionPool.run(
              conn ->
                  queryHarness.query(
                      conn, "SHOW DATABASES IN ACCOUNT", DATABASE_RESULT_SET_HANDLER));
    } catch (SQLException e) {
      throw snowflakeExceptionToIcebergException(
          SnowflakeIdentifier.ofRoot(), e, "Failed to list databases");
    } catch (InterruptedException e) {
      throw new UncheckedInterruptedException(e, "Interrupted while listing databases");
    }
    databases.forEach(
        db ->
            Preconditions.checkState(
                db.type() == SnowflakeIdentifier.Type.DATABASE,
                "Expected DATABASE, got identifier '%s'",
                db));
    return databases;
  }

  @Override
  public List<SnowflakeIdentifier> listSchemas(SnowflakeIdentifier scope) {
    StringBuilder baseQuery = new StringBuilder("SHOW SCHEMAS");
    String[] queryParams = null;
    switch (scope.type()) {

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Read the cause chain of the thrown IcebergException to see the Snowflake error code and message; fix that specific cause first
2. Verify catalog config (account URL, user, role, warehouse, auth key pair) by connecting with the same parameters via snowsql/JDBC
3. Grant the role privileges to list account databases, or use a role with ORGADMIN/ACCOUNT usage
4. Add retry for transient network/service errors and confirm network access to the Snowflake endpoint

Example fix

// before
SnowflakeCatalog catalog = ...; // misconfigured or role lacking privileges
catalog.listNamespaces(); // -> 'Failed to list databases'
// after
// check config first
// jdbc:snowflake://acct.snowflakecomputing.com?user=U&role=PROPER_ROLE&warehouse=WH
// then wrap with retry
try {
  catalog.listNamespaces();
} catch (IcebergException e) {
  // inspect e.getCause() SQLException errorCode, fix auth/role/network
}

// verify catalog config and connectivity before listing
try (Connection c = DriverManager.getConnection(jdbcUrl, user, password)) {
  c.createStatement().execute("SHOW DATABASES IN ACCOUNT");
} // throws quickly with a clear SQLException if auth/role/network are wrong

try {
  catalog.listNamespaces();
} catch (IcebergException e) {
  SQLException cause = findCause(e, SQLException.class);
  if (cause != null && isTransient(cause.getErrorCode())) {
    // retry with backoff
  } else {
    // fix auth/role/config; surface cause.getErrorCode() and message
  }
}

When it happens

Trigger: Calling listDatabases() (directly or via SnowflakeCatalog listing namespaces at the root) when the JDBC connection fails, the account is unreachable, credentials are invalid/expired, the role lacks privileges to run SHOW DATABASES, or Snowflake returns a server error.

Common situations: Wrong account URL or warehouse/role in the catalog properties; expired key-pair auth or rotated credentials; network/firewall blocking the Snowflake endpoint; role not granted any database privileges; transient Snowflake service unavailability.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

• Failed to check if database '%s' exists
• Failed to check if schema '%s' exists
• Interrupted while getting table metadata for '%s'
• Failed to load expected JDBC SnowflakeDriver - if queries fa
• Failed to list schemas for scope '%s'

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/27726dd6814ff88b. Report an issue: GitHub.