apache/iceberg · error · NoSuchFieldException

Cannot find field from 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.

Solutions

1. Check the candidate names against the actual runtime version of the target class; update them.
2. Use defaultImpl/AlwaysNull default when the field is optional, and handle the null value.
3. Ensure the declaring class is correct and the field's accessibility allows lookup (add --add-opens for JDK internals).
4. 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();

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

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
}

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

• Cannot find class; alternatives
• Cannot bind constructors
• Cannot create an instance of
• Cannot create an instance of
• Cannot create to generate and configure the client SDK…

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

Appendix: 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)