{"record":{"id":"27726dd6814ff88b","repo":"apache/iceberg","slug":"failed-to-list-databases","errorCode":null,"errorMessage":"Failed to list databases","messagePattern":"Failed to list databases","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"snowflake/src/main/java/org/apache/iceberg/snowflake/JdbcSnowflakeClient.java","lineNumber":222,"sourceCode":"    } catch (InterruptedException e) {\n      throw new UncheckedInterruptedException(\n          e, \"Interrupted while checking if schema '%s' exists\", schema);\n    }\n\n    return true;\n  }\n\n  @Override\n  public List<SnowflakeIdentifier> listDatabases() {\n    List<SnowflakeIdentifier> databases;\n    try {\n      databases =\n          connectionPool.run(\n              conn ->\n                  queryHarness.query(\n                      conn, \"SHOW DATABASES IN ACCOUNT\", DATABASE_RESULT_SET_HANDLER));\n    } catch (SQLException e) {\n      throw snowflakeExceptionToIcebergException(\n          SnowflakeIdentifier.ofRoot(), e, \"Failed to list databases\");\n    } catch (InterruptedException e) {\n      throw new UncheckedInterruptedException(e, \"Interrupted while listing databases\");\n    }\n    databases.forEach(\n        db ->\n            Preconditions.checkState(\n                db.type() == SnowflakeIdentifier.Type.DATABASE,\n                \"Expected DATABASE, got identifier '%s'\",\n                db));\n    return databases;\n  }\n\n  @Override\n  public List<SnowflakeIdentifier> listSchemas(SnowflakeIdentifier scope) {\n    StringBuilder baseQuery = new StringBuilder(\"SHOW SCHEMAS\");\n    String[] queryParams = null;\n    switch (scope.type()) {","sourceCodeStart":204,"sourceCodeEnd":240,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/snowflake/src/main/java/org/apache/iceberg/snowflake/JdbcSnowflakeClient.java#L204-L240","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the cause chain of the thrown IcebergException to see the Snowflake error code and message; fix that specific cause first","Verify catalog config (account URL, user, role, warehouse, auth key pair) by connecting with the same parameters via snowsql/JDBC","Grant the role privileges to list account databases, or use a role with ORGADMIN/ACCOUNT usage","Add retry for transient network/service errors and confirm network access to the Snowflake endpoint"],"exampleFix":"// before\nSnowflakeCatalog catalog = ...; // misconfigured or role lacking privileges\ncatalog.listNamespaces(); // -> 'Failed to list databases'\n// after\n// check config first\n// jdbc:snowflake://acct.snowflakecomputing.com?user=U&role=PROPER_ROLE&warehouse=WH\n// then wrap with retry\ntry {\n  catalog.listNamespaces();\n} catch (IcebergException e) {\n  // inspect e.getCause() SQLException errorCode, fix auth/role/network\n}","handlingStrategy":"try-catch","validationCode":"// verify catalog config and connectivity before listing\ntry (Connection c = DriverManager.getConnection(jdbcUrl, user, password)) {\n  c.createStatement().execute(\"SHOW DATABASES IN ACCOUNT\");\n} // throws quickly with a clear SQLException if auth/role/network are wrong","typeGuard":null,"tryCatchPattern":"try {\n  catalog.listNamespaces();\n} catch (IcebergException e) {\n  SQLException cause = findCause(e, SQLException.class);\n  if (cause != null && isTransient(cause.getErrorCode())) {\n    // retry with backoff\n  } else {\n    // fix auth/role/config; surface cause.getErrorCode() and message\n  }\n}","preventionTips":["Validate account URL, user, role, warehouse, and auth key pair before deploying the catalog","Grant the configured role privileges to SHOW DATABASES IN ACCOUNT","Add retry with backoff for transient SQLExceptions","Use a connectivity smoke test (SHOW DATABASES) in startup health checks"],"tags":["snowflake","jdbc","database-listing"],"backgroundTag":"database-query-failed","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}