{"record":{"id":"b3a6ec27c15e9722","repo":"apache/beam","slug":"statebackediterable-expected-terminator-of-0-or-1-but","errorCode":null,"errorMessage":"StateBackedIterable expected terminator of 0 or -1 but received %s.","messagePattern":"StateBackedIterable expected terminator of 0 or -1 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":240,"sourceCode":"    protected Iterable<T> decodeToIterable(List<T> decodedElements) {\n      return decodedElements;\n    }\n\n    @Override\n    protected Iterable<T> decodeToIterable(\n        List<T> decodedElements, long terminatorValue, InputStream in) throws IOException {\n      if (terminatorValue == -1L) {\n        long tokenLength = VarInt.decodeLong(in);\n        ByteString token = ByteString.readFrom(ByteStreams.limit(in, tokenLength));\n        return new StateBackedIterable<>(\n            cache.get(),\n            beamFnStateClient,\n            instructionId.get(),\n            StateKey.newBuilder().setRunner(StateKey.Runner.newBuilder().setKey(token)).build(),\n            getElemCoder(),\n            decodedElements);\n      } else {\n        throw new IllegalStateException(\n            String.format(\n                \"StateBackedIterable expected terminator of 0 or -1 but received %s.\",\n                terminatorValue));\n      }\n    }\n\n    @Override\n    public void encode(Iterable<T> iterable, OutputStream outStream) throws IOException {\n      if (!(iterable instanceof StateBackedIterable)) {\n        super.encode(iterable, outStream);\n        return;\n      }\n\n      StateBackedIterable<T> stateBackedIterable = (StateBackedIterable<T>) iterable;\n\n      DataOutputStream dataOutStream = new DataOutputStream(outStream);\n      // We don't know the size without traversing it so use a fixed size buffer\n      // and encode as many elements as possible into it before outputting the size followed","sourceCodeStart":222,"sourceCodeEnd":258,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/harness/src/main/java/org/apache/beam/fn/harness/state/StateBackedIterable.java#L222-L258","documentation":"StateBackedIterable.decodeToIterable throws this IllegalStateException when the encoded iterable's terminator value is neither 0 (empty) nor -1 (state-backed, fetch via state client). The terminator is an internal wire-format marker, so any other value means the encoded bytes are corrupt or were produced by an incompatible coder version.","triggerScenarios":"Decoding a StateBackedIterable whose byte stream contains a terminator int other than 0 or -1 — typically from corrupted data, manual crafting, or a wire format change between Beam versions.","commonSituations":"Data written by a different Beam version being re-read; corrupted checkpoints/Fn API data streams; custom code that reuses or forks the StateBackedIterable wire format.","solutions":["Verify the data was written by a compatible Beam SDK version","Re-run the bundle/job so the iterable is re-encoded from source data","Check for data corruption in the transport (data channel) and inspect the encoded bytes","Do not manually construct StateBackedIterable-encoded bytes"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Before decoding, check data provenance\nif (!Objects.equals(beamVersion, expectedWriterVersion)) {\n  throw new IllegalStateException(\"StateBackedIterable data from incompatible Beam version\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Read/write data with the same Beam version","Never hand-craft StateBackedIterable encoded bytes","Treat corrupted transport data by re-running the bundle"],"tags":["java","apache-beam","wire-format","corrupt-data"],"backgroundTag":"internal-invariant-violation","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"}