square/retrofit · error · NullPointerException

mapper == null

Error message

mapper == null

What it means

NullPointerException thrown by JacksonConverterFactory.create(ObjectMapper, MediaType) when the supplied ObjectMapper is null (line 56). The factory uses the mapper to construct JavaType, ObjectReader, and ObjectWriter for every conversion (lines 84-97), so a null mapper is unusable and the constructor fails fast rather than NPE-ing later during a request.

Source

Thrown at retrofit-converters/jackson/src/main/java/retrofit2/converter/jackson/JacksonConverterFactory.java:56

 */
public final class JacksonConverterFactory extends Converter.Factory {
  private static final MediaType DEFAULT_MEDIA_TYPE =
      MediaType.get("application/json; charset=UTF-8");

  /** Create an instance using a default {@link ObjectMapper} instance for conversion. */
  public static JacksonConverterFactory create() {
    return new JacksonConverterFactory(new ObjectMapper(), DEFAULT_MEDIA_TYPE, false);
  }

  /** Create an instance using {@code mapper} for conversion. */
  public static JacksonConverterFactory create(ObjectMapper mapper) {
    return create(mapper, DEFAULT_MEDIA_TYPE);
  }

  /** Create an instance using {@code mapper} and {@code mediaType} for conversion. */
  @SuppressWarnings("ConstantConditions") // Guarding public API nullability.
  public static JacksonConverterFactory create(ObjectMapper mapper, MediaType mediaType) {
    if (mapper == null) throw new NullPointerException("mapper == null");
    if (mediaType == null) throw new NullPointerException("mediaType == null");
    return new JacksonConverterFactory(mapper, mediaType, false);
  }

  private final ObjectMapper mapper;
  private final MediaType mediaType;
  private final boolean streaming;

  private JacksonConverterFactory(ObjectMapper mapper, MediaType mediaType, boolean streaming) {
    this.mapper = mapper;
    this.mediaType = mediaType;
    this.streaming = streaming;
  }

  /**
   * Return a new factory which streams serialization of request messages to bytes on the HTTP thread
   * This is either the calling thread for {@link Call#execute()}, or one of OkHttp's background
   * threads for {@link Call#enqueue}. Response bytes are always converted to message instances on

View on GitHub (pinned to d0b112dad0)

Solutions

1. If you do not need custom Jackson configuration, use the no-arg `JacksonConverterFactory.create()` which builds a default ObjectMapper.
2. Ensure the ObjectMapper is non-null: `Objects.requireNonNull(mapper, "mapper")` before passing.
3. Fix the DI binding so the ObjectMapper bean is always provided with the correct qualifier/scope.

Example fix

// before
ObjectMapper mapper = config.maybeMapper(); // null when unconfigured
Retrofit retrofit = new Retrofit.Builder()
    .addConverterFactory(JacksonConverterFactory.create(mapper))
    .build();

// after
Retrofit retrofit = new Retrofit.Builder()
    .addConverterFactory(JacksonConverterFactory.create()) // default ObjectMapper
    .build();

// Validate before wiring the converter into Retrofit.
ObjectMapper mapper =
    Objects.requireNonNull(config.buildObjectMapper(), "mapper must not be null");
JacksonConverterFactory factory = JacksonConverterFactory.create(mapper);

try {
  factory = JacksonConverterFactory.create(mapper);
} catch (NullPointerException e) {
  throw new IllegalStateException("ObjectMapper was not provided; fix the DI binding", e);
}

When it happens

Trigger: Calling `JacksonConverterFactory.create(mapper)` or `create(mapper, mediaType)` where `mapper` is null — e.g. a DI-provided ObjectMapper bean that was not bound, a factory method returning null, or explicitly passing null.

Common situations: Spring/Guice DI misconfiguration where the ObjectMapper bean is missing or has the wrong qualifier; a builder helper that returns null on config failure; refactor that removed the bean definition; test neglecting to set the mapper.

Related errors

• gson == null
• context == null
• ListenableFuture return type must be parameterized as Listen
• Response must be parameterized as Response<Foo> or Response<
• CompletableFuture return type must be parameterized as Compl

AI-assisted analysis of square/retrofit@d0b112dad0 (2026-08-04). Data as JSON: /data/errors/3c0d695b9f11e58e.json. Report an issue: GitHub.