apache/iceberg · error · UncheckedIOException

Cannot update namespace '%s': %s

Error message

Cannot update namespace '%s': %s

What it means

The catch-all in updateProperties: any other BaseNessieClientServerException from the commit (server errors, quota/validation errors, unexpected conflict types) is wrapped in an UncheckedIOException 'Cannot update namespace %s: <server message>'. It means the namespace property commit failed for a reason not covered by the more specific handlers.

Source

Thrown at nessie/src/main/java/org/apache/iceberg/nessie/NessieIcebergClient.java:447

          NessieUtil.extractSingleConflict(e, EnumSet.of(Conflict.ConflictType.KEY_DOES_NOT_EXIST));
      if (conflict.isPresent()
          && conflict.get().conflictType() == Conflict.ConflictType.KEY_DOES_NOT_EXIST) {
        throw new NoSuchNamespaceException(e, "Namespace does not exist: %s", namespace);
      }
      throw new UncheckedIOException(
          String.format(
              "Cannot update properties on namespace '%s': %s", namespace, e.getMessage()),
          e);
    } catch (NessieContentNotFoundException e) {
      throw new NoSuchNamespaceException("Namespace does not exist: %s", namespace);
    } catch (NessieReferenceNotFoundException e) {
      throw new UncheckedIOException(
          String.format(
              "Cannot update properties on namespace '%s': ref '%s' is no longer valid.",
              namespace, getRef().getName()),
          e);
    } catch (BaseNessieClientServerException e) {
      throw new UncheckedIOException(
          String.format("Cannot update namespace '%s': %s", namespace, e.getMessage()), e);
    }
  }

  public void renameTable(TableIdentifier from, TableIdentifier to) {
    renameContent(from, to, Content.Type.ICEBERG_TABLE);
  }

  public void renameView(TableIdentifier from, TableIdentifier to) {
    renameContent(from, to, Content.Type.ICEBERG_VIEW);
  }

  private void renameContent(TableIdentifier from, TableIdentifier to, Content.Type type) {
    getRef().checkMutable();

    IcebergContent existingFromContent = fetchContent(from);
    validateFromContentForRename(from, type, existingFromContent);

View on GitHub (pinned to 86d9c8fc54)

Solutions

  1. Read the embedded e.getMessage() to identify the server-side cause and address it directly.
  2. Check Nessie server health/logs for the corresponding request failure.
  3. Verify Nessie client and server versions are compatible (same major/minor family).
  4. Retry with backoff if the server was temporarily unhealthy; escalate with server logs if persistent.

Example fix

// before
catalog.setProperties(ns, Map.of("k", "\u0000bad")); // server rejects, generic UncheckedIOException
// after
catalog.setProperties(ns, Map.of("k", "bad")); // use server-accepted property values
Defensive patterns

Strategy: try-catch

Try / catch

try {
  catalog.setProperties(ns, props);
} catch (UncheckedIOException e) {
  LOGGER.error("Nessie server rejected namespace update: {}", e.getMessage(), e);
  throw new ServiceException(e); // surface server message to operators
}

Prevention

When it happens

Trigger: setProperties/removeProperties hitting any Nessie server-side exception not classified as reference-conflict, content-not-found, or reference-not-found — e.g. internal server errors, bad request from malformed properties, or license/quota errors.

Common situations: Nessie server partially unavailable or erroring; property values or keys rejected server-side; Nessie client/server version mismatch producing unrecognized error classes; proxy/gateway injecting error responses.

Understand the failure class

Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.

Related errors

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