What causes "Cannot find field from candidates: ${candidates}" in apache/iceberg?

Check the candidate names against the actual runtime version of the target class; update them.

apache/iceberg · error · NoSuchFieldException

Cannot find field from candidates: ${candidates}

Error message

Cannot find field from candidates: ${candidates}

What it means

DynFields.Builder.buildChecked() throws NoSuchFieldException when none of the candidate field names resolved to a real field and no default was configured. The message lists all candidate names that were tried. This is the checked variant that forces callers to handle lookup failure.

Source

Thrown at common/src/main/java/org/apache/iceberg/common/DynFields.java:385

      return this;
    }

    /**
     * Returns the first valid implementation as a UnboundField or throws a NoSuchFieldException if
     * there is none.
     *
     * @param <T> Java class stored in the field
     * @return a {@link UnboundField} with a valid implementation
     * @throws NoSuchFieldException if no implementation was found
     */
    @SuppressWarnings("unchecked")
    public <T> UnboundField<T> buildChecked() throws NoSuchFieldException {
      if (field != null) {
        return (UnboundField<T>) field;
      } else if (defaultAlwaysNull) {
        return (UnboundField<T>) AlwaysNull.INSTANCE;
      } else {
        throw new NoSuchFieldException(
            "Cannot find field from candidates: " + Joiner.on(", ").join(candidates));
      }
    }

    /**
     * Returns the first valid implementation as a BoundMethod or throws a NoSuchMethodException if
     * there is none.
     *
     * @param target an Object on which to get and set the field
     * @param <T> Java class stored in the field
     * @return a {@link BoundField} with a valid implementation and target
     * @throws IllegalStateException if the method is static
     * @throws IllegalArgumentException if the receiver's class is incompatible
     * @throws NoSuchFieldException if no implementation was found
     */
    public <T> BoundField<T> buildChecked(Object target) throws NoSuchFieldException {
      return this.<T>buildChecked().bind(target);
    }

View on GitHub (pinned to 86d9c8fc54)

Solutions

Check the candidate names against the actual runtime version of the target class; update them.
Use defaultImpl/AlwaysNull default when the field is optional, and handle the null value.
Ensure the declaring class is correct and the field's accessibility allows lookup (add --add-opens for JDK internals).
Prefer buildChecked() at startup so misconfiguration fails fast with the full candidate list.

Example fix

// before
UnboundField<String> f = DynFields.builder().hiddenImpl("Conf", "oldName").buildChecked();
// after
UnboundField<String> f = DynFields.builder()
    .hiddenImpl("Conf", "newName")
    .hiddenImpl("Conf", "oldName")
    .defaultAlwaysNull()
    .buildChecked();

Defensive patterns

Strategy: try-catch

Validate before calling

boolean fieldExists;
try {
  TargetClass.class.getDeclaredField("fieldName");
  fieldExists = true;
} catch (NoSuchFieldException e) {
  fieldExists = false;
}
if (!fieldExists) { /* use alternative name or default */ }

Try / catch

try {
  UnboundField<T> f = DynFields.builder().hiddenImpl(Cls.class, "name").buildChecked();
} catch (NoSuchFieldException e) {
  // field missing in this runtime version: use fallback or fail with a clear message
}

Prevention

Provide multiple candidate field names spanning supported library versions
Verify field names against the exact runtime version before deployment
Use defaultAlwaysNull() for optional fields and null-check at use sites
For JDK internals, add the required --add-opens flags to the JVM

When it happens

Trigger: DynFields.builder().hiddenImpl("a.C", "field").buildChecked() where the target class has none of the candidate fields and defaultAlwaysNull is not set.

Common situations: Reflecting into internals that changed across library versions (field renamed/removed); typos in field names; accessing a field on the wrong class; accessing hidden fields in JDKs where reflection into non-exported packages is blocked.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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