{"record":{"id":"e85b9f6f9571e69d","repo":"apache/beam","slug":"model-coder-not-registered-for-s-perhaps-this-is-a-fat-jar","errorCode":null,"errorMessage":"Model coder not registered for %s. Perhaps this is a fat jar built with missing ServiceLoader entries?","messagePattern":"Model coder not registered for (.+?)\\. Perhaps this is a fat jar built with missing ServiceLoader entries\\?","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/util/construction/CoderTranslation.java","lineNumber":268,"sourceCode":"    }\n  }\n\n  private static Coder<?> fromCustomCoder(RunnerApi.Coder protoCoder) throws IOException {\n    return (Coder<?>)\n        SerializableUtils.deserializeFromByteArray(\n            protoCoder.getSpec().getPayload().toByteArray(), \"Custom Coder Bytes\");\n  }\n\n  /**\n   * Explicitly validate that required coders are registered.\n   *\n   * <p>Called early to give avoid significantly more obscure error later if this precondition is\n   * not satisfied.\n   */\n  public static void verifyModelCodersRegistered() {\n    for (String urn : new ModelCoderRegistrar().getCoderURNs().values()) {\n      if (!getKnownCoderUrns().inverse().containsKey(urn)) {\n        throw new IllegalStateException(\n            \"Model coder not registered for \"\n                + urn\n                + \". Perhaps this is a fat jar built with missing ServiceLoader entries?\");\n      }\n    }\n  }\n}\n","sourceCodeStart":250,"sourceCodeEnd":276,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/util/construction/CoderTranslation.java#L250-L276","documentation":"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.","triggerScenarios":"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.","commonSituations":"Uber/fat jar built with maven-shade without ServicesResourceTransformer; multiple Beam SDK versions on the classpath; runner classloader isolation (Flink/Spark) hiding service files.","solutions":["Add ServicesResourceTransformer to maven-shade-plugin so META-INF/services files merge","Check for duplicate/mixed org.apache.beam artifact versions with mvn dependency:tree and align them","Ensure the Beam SDK jar is on the runner-visible classpath, not filtered by exclusion rules","Call verifyModelCodersRegistered() in a smoke test to catch packaging regressions in CI"],"exampleFix":"// before\n<plugin>\n  <groupId>org.apache.maven.plugins</groupId>\n  <artifactId>maven-shade-plugin</artifactId>\n  <!-- no transformers -->\n</plugin>\n// after\n<plugin>\n  <artifactId>maven-shade-plugin</artifactId>\n  <configuration>\n    <transformers>\n      <transformer implementation=\"org.apache.maven.plugins.shade.resource.ServicesResourceTransformer\"/>\n    </transformers>\n  </configuration>\n</plugin>","handlingStrategy":"validation","validationCode":"try {\n  CoderTranslation.verifyModelCodersRegistered();\n} catch (IllegalStateException e) {\n  throw new IllegalStateException(\"Beam packaging broken: \" + e.getMessage(), e);\n}","typeGuard":null,"tryCatchPattern":"try {\n  CoderTranslation.verifyModelCodersRegistered();\n} catch (IllegalStateException e) {\n  // missing ServiceLoader entries in fat jar\n  throw new IllegalStateException(\"rebuild jar with ServicesResourceTransformer\", e);\n}","preventionTips":["Configure maven-shade ServicesResourceTransformer in fat-jar builds","Check classpath for mixed Beam SDK versions with dependency:tree","Add an early-boot unit test calling verifyModelCodersRegistered()"],"tags":["java","beam","serviceloader","packaging"],"backgroundTag":"missing-dependency","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}