apache/beam · error · IllegalStateException

Model coder not registered for

Error message

Model coder not registered for %s. Perhaps this is a fat jar built with missing ServiceLoader entries?

What it means

CoderTranslation.verifyModelCodersRegistered checks that every Beam model coder URN has a matching local Coder translation; if a URN from ModelCoderRegistrar is missing from the known-URN map it throws IllegalStateException, indicating the runtime can't round-trip core coders — almost always a packaging problem.

Solutions

1. Add ServicesResourceTransformer to maven-shade-plugin so META-INF/services files merge
2. Check for duplicate/mixed org.apache.beam artifact versions with mvn dependency:tree and align them
3. Ensure the Beam SDK jar is on the runner-visible classpath, not filtered by exclusion rules
4. Call verifyModelCodersRegistered() in a smoke test to catch packaging regressions in CI

Example fix

// before
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-shade-plugin</artifactId>
  <!-- no transformers -->
</plugin>
// after
<plugin>
  <artifactId>maven-shade-plugin</artifactId>
  <configuration>
    <transformers>
      <transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
    </transformers>
  </configuration>
</plugin>

try {
  CoderTranslation.verifyModelCodersRegistered();
} catch (IllegalStateException e) {
  throw new IllegalStateException("Beam packaging broken: " + e.getMessage(), e);
}

try {
  CoderTranslation.verifyModelCodersRegistered();
} catch (IllegalStateException e) {
  // missing ServiceLoader entries in fat jar
  throw new IllegalStateException("rebuild jar with ServicesResourceTransformer", e);
}

When it happens

Trigger: Calling verifyModelCodersRegistered() (invoked early during pipeline construction/execution) in a JVM where the ServiceLoader cannot see CoderTranslatorRegistrar entries — e.g. fat jar missing services files, or Beam SDK classes split across conflicting classloaders.

Common situations: Uber/fat jar built with maven-shade without ServicesResourceTransformer; multiple Beam SDK versions on the classpath; runner classloader isolation (Flink/Spark) hiding service files.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• Unable to find CoderTranslator for known Coder
• A list of URNs for overriding transforms was provided but…
• A cannot be expanded
• A transform cannot be initiated using the provided config…
• AVRO schema doesn't match row schema. Row schema

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/e85b9f6f9571e69d. Report an issue: GitHub.

Appendix: source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/util/construction/CoderTranslation.java:268

    }
  }

  private static Coder<?> fromCustomCoder(RunnerApi.Coder protoCoder) throws IOException {
    return (Coder<?>)
        SerializableUtils.deserializeFromByteArray(
            protoCoder.getSpec().getPayload().toByteArray(), "Custom Coder Bytes");
  }

  /**
   * Explicitly validate that required coders are registered.
   *
   * <p>Called early to give avoid significantly more obscure error later if this precondition is
   * not satisfied.
   */
  public static void verifyModelCodersRegistered() {
    for (String urn : new ModelCoderRegistrar().getCoderURNs().values()) {
      if (!getKnownCoderUrns().inverse().containsKey(urn)) {
        throw new IllegalStateException(
            "Model coder not registered for "
                + urn
                + ". Perhaps this is a fat jar built with missing ServiceLoader entries?");
      }
    }
  }
}

View on GitHub (pinned to 12126d8942)