{"record":{"id":"36f42e272d3049ad","repo":"apache/beam","slug":"class-is-not-registered","errorCode":null,"errorMessage":"Class is not registered","messagePattern":"Class is not registered","errorType":"exception","errorClass":"CoderException","httpStatus":null,"severity":"error","filePath":"sdks/java/extensions/kryo/src/main/java/org/apache/beam/sdk/extensions/kryo/KryoCoder.java","lineNumber":214,"sourceCode":"      throw new CoderException(\"Cannot encode a null value.\");\n    }\n    final OutputChunked outputChunked = kryoState.getOutputChunked();\n    outputChunked.setOutputStream(outStream);\n    try {\n      kryoState.getKryo().writeClassAndObject(outputChunked, value);\n      outputChunked.endChunk();\n      outputChunked.flush();\n    } catch (KryoException e) {\n      outputChunked.reset();\n      if (e.getCause() instanceof EOFException) {\n        throw (EOFException) e.getCause();\n      }\n      throw new CoderException(\"Cannot encode given object of type [\" + value.getClass() + \"].\", e);\n    } catch (IllegalArgumentException e) {\n      String message = e.getMessage();\n      if (message != null) {\n        if (message.startsWith(\"Class is not registered\")) {\n          throw new CoderException(message);\n        }\n      }\n      throw e;\n    }\n  }\n\n  @Override\n  public T decode(InputStream inStream) throws IOException {\n    final KryoState kryoState = KryoState.get(this);\n    final InputChunked inputChunked = kryoState.getInputChunked();\n    inputChunked.setInputStream(inStream);\n    try {\n      @SuppressWarnings(\"unchecked\")\n      final T instance = (T) kryoState.getKryo().readClassAndObject(inputChunked);\n      return instance;\n    } catch (KryoException e) {\n      throw new CoderException(\"Cannot decode object from input stream.\", e);\n    }","sourceCodeStart":196,"sourceCodeEnd":232,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/extensions/kryo/src/main/java/org/apache/beam/sdk/extensions/kryo/KryoCoder.java#L196-L232","documentation":"Kryo with registration required throws IllegalArgumentException(\"Class is not registered: ...\") when it encounters an unregistered class. KryoCoder detects that message prefix and rethrows it as a CoderException so users see the registration problem clearly; any other IllegalArgumentException propagates unchanged.","triggerScenarios":"Kryo instance configured with registrationRequired=true and the pipeline encodes an object whose class (or nested field class) was never registered via a KryoRegistrar / KryoOptions registration list.","commonSituations":"Adding a new event type to the pipeline without adding it to the Kryo registrations; nested types inside a registered class; lambda/anonymous class fields; upgrade changing generated class names (Avro/protobuf classes).","solutions":["Register the reported class (from the message text) in your KryoRegistrar / beam KryoOptions registration list","Register all nested field types, not just the top-level class","Alternatively disable registrationRequired (kryo.setRegistrationRequired(false)) at the cost of serialization size/performance","Use kryo.register(Class, Serializer) with a custom serializer for classes you can't modify"],"exampleFix":"// before\nkryo.setRegistrationRequired(true); // MyEvent not registered\n// after\nkryo.setRegistrationRequired(true);\nkryo.register(MyEvent.class);\nkryo.register(MyEvent.Inner.class);","handlingStrategy":"validation","validationCode":"java\n// before pipeline run\nkryo.register(MyEvent.class);\nkryo.register(MyEvent.Inner.class); // register nested types too","typeGuard":null,"tryCatchPattern":"java\ntry {\n  coder.encode(value, out);\n} catch (CoderException e) {\n  if (e.getMessage().startsWith(\"Class is not registered\")) {\n    log.severe(\"Register this class with Kryo: \" + e.getMessage());\n  }\n}","preventionTips":["Maintain a central KryoRegistrar listing all pipeline types","Re-run registration checks when adding new event/record classes","Keep registrationRequired=true in CI to surface gaps early","Watch for renamed generated classes after schema/Avro upgrades"],"tags":["java","beam","kryo","serialization","class-registration"],"backgroundTag":"class-not-found","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"}