apache/iceberg · error · UncheckedSQLException

Failed to get lock information for %s

Error message

Failed to get lock information for %s

What it means

JdbcLockFactory.JdbcLock.instanceId() throws UncheckedSQLException when the SQL query to read lock information for the given lock type fails. The message names the lock type (task/recovery). This means the lock owner could not be determined due to a database access problem.

Source

Thrown at flink/v2.2/flink/src/main/java/org/apache/iceberg/flink/maintenance/api/JdbcLockFactory.java:303

        return pool.run(
            conn -> {
              try (PreparedStatement sql = conn.prepareStatement(GET_LOCK_SQL)) {
                sql.setString(1, type.key);
                sql.setString(2, lockId);
                try (ResultSet rs = sql.executeQuery()) {
                  if (rs.next()) {
                    return rs.getString(1);
                  } else {
                    return null;
                  }
                }
              }
            });
      } catch (InterruptedException e) {
        Thread.currentThread().interrupt();
        throw new UncheckedInterruptedException(e, "Interrupted during unlock");
      } catch (SQLException e) {
        throw new UncheckedSQLException(e, "Failed to get lock information for %s", type);
      }
    }
  }

  private enum Type {
    MAINTENANCE("m"),
    RECOVERY("r");

    private final String key;

    Type(String key) {
      this.key = key;
    }
  }
}

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Read the wrapped SQLException cause and restore database connectivity/health.
2. Verify the lock table exists with the expected schema for the given lock type prefix (m/r).
3. Grant the maintenance user read access to the lock table.
4. Validate your JDBC URL/credentials against the chosen database and re-run the maintenance trigger.

Example fix

// before
String url = "jdbc:postgresql://db:5432/iceberg"; // lock table missing
// after
// recreate catalog/lock tables or point to the catalog's database
String url = "jdbc:postgresql://db:5432/iceberg_catalog";

try (Connection c = DriverManager.getConnection(jdbcUrl, user, pass)) {
  ResultSet rs = c.getMetaData().getTables(null, null, "iceberg_locks", new String[]{"TABLE"});
  if (!rs.next()) throw new IllegalStateException("Lock table missing");
}

try { String id = lock.instanceId(); } catch (UncheckedSQLException e) { log.error("instanceId failed: {}", e.getCause(), e); /* check lock table & DB health */ }

When it happens

Trigger: instanceId() queries the lock table and the JDBC driver throws SQLException: connection failure, missing/renamed lock table, insufficient privileges, or unsupported SQL for the backend.

Common situations: Database outage or failover during maintenance; lock table absent because the JDBC catalog was never initialized; restricted DB user lacking SELECT on the lock table; using a JDBC backend whose SQL dialect differs from the expected pattern.

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 the state of the lock %s
• Cannot initialize JDBC table maintenance lock
• Failed to create %s lock
• Failed to check the state of the lock %s
• Failed to remove lock %s

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