{"record":{"id":"4e0c84102283de24","repo":"apache/beam","slug":"unable-to-construct-coder-s-expected-translation-context-s","errorCode":null,"errorMessage":"Unable to construct coder %s. Expected translation context %s but received %s.","messagePattern":"Unable to construct coder (.+?)\\. Expected translation context (.+?) but received (.+?)\\.","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"sdks/java/harness/src/main/java/org/apache/beam/fn/harness/state/StateBackedIterable.java","lineNumber":353,"sourceCode":"    @Override\n    public List<? extends org.apache.beam.sdk.coders.Coder<?>> getComponents(\n        StateBackedIterable.Coder<?> from) {\n      return Collections.<org.apache.beam.sdk.coders.Coder<?>>singletonList(from.getElemCoder());\n    }\n\n    @Override\n    public StateBackedIterable.Coder<?> fromComponents(\n        List<org.apache.beam.sdk.coders.Coder<?>> components,\n        byte[] payload,\n        TranslationContext context) {\n      if (context instanceof StateBackedIterableTranslationContext) {\n        return new StateBackedIterable.Coder<>(\n            ((StateBackedIterableTranslationContext) context).getCache(),\n            ((StateBackedIterableTranslationContext) context).getStateClient(),\n            ((StateBackedIterableTranslationContext) context).getCurrentInstructionId(),\n            Iterables.getOnlyElement(components));\n      } else {\n        throw new IllegalStateException(\n            String.format(\n                \"Unable to construct coder %s. Expected translation context %s but received %s.\",\n                STATE_BACKED_ITERABLE_CODER_URN,\n                StateBackedIterableTranslationContext.class.getName(),\n                context.getClass().getName()));\n      }\n    }\n  }\n}\n","sourceCodeStart":335,"sourceCodeEnd":363,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/harness/src/main/java/org/apache/beam/fn/harness/state/StateBackedIterable.java#L335-L363","documentation":"StateBackedIterable.Coder.fromComponents throws this IllegalStateException when the Coder.Context passed during coder construction is not a StateBackedIterableTranslationContext. The coder requires the translation context to carry a cache token, state client, and current instruction ID; receiving a plain context means translation was set up incorrectly.","triggerScenarios":"Translating/constructing a StateBackedIterable coder in a context that is not an instance of StateBackedIterableTranslationContext — i.e. code path bypassing the harness's state-backed-iterable translation setup.","commonSituations":"Runner not registering the state-backed iterable translation context; custom pipeline visitors or tests constructing the coder directly with new Coder.Context(false); Beam version mismatch where the context class changed.","solutions":["Ensure translation runs through the Beam Fn harness path that supplies StateBackedIterableTranslationContext","Check runner and SDK harness versions match (context class/package must be identical)","In tests, build the context via the harness helpers rather than a bare Coder.Context","Compare context.getClass().getName() in the message against the expected class name to spot duplicate-classloader issues"],"exampleFix":"// before\nnew StateBackedIterable.Coder<>(new Coder.Context(true), cache, client, elemCoder);\n// after: use the harness translation context\nStateBackedIterableTranslationContext ctx =\n    new StateBackedIterableTranslationContext(cache, client, instructionId);\nnew StateBackedIterable.Coder<>(ctx, cache, client, elemCoder);","handlingStrategy":"type-guard","validationCode":"if (!(context instanceof StateBackedIterableTranslationContext)) {\n  throw new IllegalArgumentException(\"wrong coder context: \" + context.getClass());\n}","typeGuard":"boolean hasTranslationContext(Coder.Context ctx) {\n  return ctx instanceof StateBackedIterableTranslationContext;\n}","tryCatchPattern":"try {\n  return StateBackedIterable.Coder.of(cache, client, instructionId, elemCoder);\n} catch (IllegalStateException e) {\n  throw new IllegalStateException(\"state-backed coder needs harness translation context\", e);\n}","preventionTips":["Construct this coder only inside Beam Fn harness translation","Keep runner and SDK harness versions aligned","Avoid `new Coder.Context(...)` in state-backed iterable paths"],"tags":["java","apache-beam","coder-context","translation"],"backgroundTag":"invalid-argument-value","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"}