What causes "Failed to insert: %d of %d succeeded" in apache/iceberg?

Retry the operation; if properties were partially inserted, remove duplicates and re-set them

apache/iceberg · error · IllegalStateException

Failed to insert: %d of %d succeeded

Error message

Failed to insert: %d of %d succeeded

What it means

insertProperties() issues a multi-row insert of namespace properties via JdbcUtil.insertPropertiesStatement and expects exactly properties.size() inserted rows. If execute() returns fewer, it throws IllegalStateException "Failed to insert: %d of %d succeeded" — an internal invariant violation meaning the catalog state is now partially updated.

Source

Thrown at core/src/main/java/org/apache/iceberg/jdbc/JdbcCatalog.java:854

    return ImmutableMap.<String, String>builder().putAll(entries).buildOrThrow();
  }

  private boolean insertProperties(Namespace namespace, Map<String, String> properties) {
    String namespaceName = JdbcUtil.namespaceToString(namespace);
    String[] args =
        properties.entrySet().stream()
            .flatMap(
                entry -> Stream.of(catalogName, namespaceName, entry.getKey(), entry.getValue()))
            .toArray(String[]::new);

    int insertedRecords = execute(JdbcUtil.insertPropertiesStatement(properties.size()), args);

    if (insertedRecords == properties.size()) {
      return true;
    }

    throw new IllegalStateException(
        String.format(
            Locale.ROOT,
            "Failed to insert: %d of %d succeeded",
            insertedRecords,
            properties.size()));
  }

  private boolean updateProperties(Namespace namespace, Map<String, String> properties) {
    String namespaceName = JdbcUtil.namespaceToString(namespace);
    Stream<String> caseArgs =
        properties.entrySet().stream()
            .flatMap(entry -> Stream.of(entry.getKey(), entry.getValue()));
    Stream<String> whereArgs =
        Stream.concat(Stream.of(catalogName, namespaceName), properties.keySet().stream());

    String[] args = Stream.concat(caseArgs, whereArgs).toArray(String[]::new);

    int updatedRecords = execute(JdbcUtil.updatePropertiesStatement(properties.size()), args);

View on GitHub (pinned to 86d9c8fc54)

Solutions

Retry the operation; if properties were partially inserted, remove duplicates and re-set them
Avoid concurrent writers to the same namespace properties, or use a database whose insert is atomic per statement
Inspect the namespace properties after failure and reconcile (setProperties again with the full map)
Verify the catalog table's primary key/unique constraints match what this Iceberg version expects

Example fix

// before
catalog.setProperties(ns, newProps);
// after
Map<String, String> existing = catalog.loadNamespaceMetadata(ns);
Map<String, String> onlyNew = newProps.entrySet().stream()
    .filter(e -> !existing.containsKey(e.getKey()))
    .collect(Collectors.toMap(Map.Entry::getKey, Map.Entry::getValue));
catalog.setProperties(ns, onlyNew);

Defensive patterns

Strategy: validation

Validate before calling

Map<String, String> existing = catalog.namespaceExists(ns)
    ? catalog.loadNamespaceMetadata(ns)
    : Map.of();
Set<String> dupes = new HashSet<>(props.keySet());
dupes.retainAll(existing.keySet());
if (!dupes.isEmpty()) throw new IllegalStateException("Keys already present: " + dupes);

Try / catch

try {
  catalog.setProperties(ns, props);
} catch (IllegalStateException e) {
  if (e.getMessage().startsWith("Failed to insert")) {
    // partial state: reconcile by re-reading and re-setting full property map
    Map<String, String> current = catalog.loadNamespaceMetadata(ns);
    current.putAll(props);
    catalog.setProperties(ns, current);
  } else throw e;
}

Prevention

Avoid concurrent setProperties on the same namespace
Pre-check for existing keys before bulk insert of properties
Reconcile catalog properties after any partial-insert failure
Verify unique constraints on the properties catalog table

When it happens

Trigger: createNamespace or setProperties where the bulk INSERT matches fewer rows than submitted: usually a constraint violation on some rows (duplicate property keys for the namespace, e.g. concurrent setProperties inserting the same key) that the JDBC driver partially applied instead of failing atomically.

Common situations: Concurrent clients inserting the same property key for the same namespace without ON CONFLICT semantics; databases with quirks around batch insert counts; catalog schema modified so unique constraints differ.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

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