apache/druid · error · ProvisionException

JsonConfigurator requires Jackson-annotated Config objects t

Error message

JsonConfigurator requires Jackson-annotated Config objects to have field annotations. %s doesn't

What it means

JsonConfigurator requires that every property of a config class be Jackson-deserializable from runtime properties, and it enforces that each serialized bean property has a backing field annotated with @JsonProperty. If any introspected property lacks a field or the field lacks @JsonProperty, verifyClazzIsConfigurable throws this ProvisionException at injector startup.

Source

Thrown at processing/src/main/java/org/apache/druid/guice/JsonConfigurator.java:290

        }
      }
      catch (NoSuchMethodException e) {
        throw new ProvisionException(
            StringUtils.format(
                "JsonConfigurator requires default classes to have zero-arg constructors. %s doesn't",
                defaultClass
            )
        );
      }
    }

    final List<BeanPropertyDefinition> beanDefs = mapper.getSerializationConfig()
                                                        .introspect(mapper.constructType(clazz))
                                                        .findProperties();
    for (BeanPropertyDefinition beanDef : beanDefs) {
      final AnnotatedField field = beanDef.getField();
      if (field == null || !field.hasAnnotation(JsonProperty.class)) {
        throw new ProvisionException(
            StringUtils.format(
                "JsonConfigurator requires Jackson-annotated Config objects to have field annotations. %s doesn't",
                clazz
            )
        );
      }
    }
  }

  private static <T> Optional<Method> findJsonCreatorFactoryMethod(Class<T> clazz)
  {
    return Arrays.stream(clazz.getMethods())
                 .filter(m -> m.getAnnotation(JsonCreator.class) != null
                              && m.getParameterCount() == 0
                              && m.getReturnType()
                                  .equals(clazz))
                 .findFirst();

View on GitHub (pinned to 9b90983fd2)

Solutions

Annotate every field of the config class with @JsonProperty
Add fields backing any getter-only properties, or remove the getter from the config class
Use a @JsonCreator/@JsonProperty constructor if field annotation is impossible, per the class's other requirements
Keep config classes as simple, Jackson-annotated POJOs per Druid conventions

Example fix

// before
public class MyConfig {
  private String name;
  public String getName() { return name; }
}
// after
public class MyConfig {
  @JsonProperty public String name;
}

Defensive patterns

Strategy: validation

Validate before calling

for (Field f : clazz.getDeclaredFields()) {
  if (!f.isAnnotationPresent(JsonProperty.class)) throw new IllegalStateException("Missing @JsonProperty: " + f);
}

Type guard

boolean hasFieldAnnotations(Class<?> c) {
  return new ObjectMapper().getSerializationConfig().introspect(new ObjectMapper().constructType(c))
      .findProperties().stream().allMatch(p -> p.getField() != null && p.getField().hasAnnotation(JsonProperty.class));
}

Try / catch

try { injector.getInstance(configKey); } catch (ProvisionException e) { if (e.getMessage().contains("field annotations")) log.error("Annotate config fields with @JsonProperty"); throw e; }

Prevention

Convention: every field in a config class gets @JsonProperty
Avoid getter-only derived properties in config classes
Run a reflection-based unit test that verifies all extension config classes comply

When it happens

Trigger: configurate() calls verifyClazzIsConfigurable; Jackson introspection finds a BeanPropertyDefinition whose getField() is null (getter-only property) or whose AnnotatedField.hasAnnotation(JsonProperty.class) is false.

Common situations: Config class uses getter/setter style without @JsonProperty on fields; a derived/read-only getter property with no backing field; Lombok or code-generated classes without Jackson annotations; migrating a POJO from another framework.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

AI-assisted analysis of apache/druid@9b90983fd2 (2026-09-07). Data as JSON: /api/errors/98751246b255ab26. Report an issue: GitHub.