{"record":{"id":"68648bbdaa84dd48","repo":"apache/druid","slug":"invalid-stream-header-id-s-position-d","errorCode":null,"errorMessage":"Invalid stream header (id = %s, position = %d)","messagePattern":"Invalid stream header \\(id = (.+?), position = (.+?)\\)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"processing/src/main/java/org/apache/druid/frame/channel/ReadableByteChunksFrameChannel.java","lineNumber":406,"sourceCode":"        return rac;\n\n      default:\n        throw new ISE(\"Unexpected marker type[%d]\", markerType);\n    }\n  }\n\n  @GuardedBy(\"lock\")\n  private void updateStreamState()\n  {\n    if (streamPart == StreamPart.MAGIC) {\n      if (bytesBuffered >= FrameFileWriter.MAGIC.length) {\n        final Memory memory = copyFromQueuedChunks(FrameFileWriter.MAGIC.length);\n\n        if (memory.equalTo(0, Memory.wrap(FrameFileWriter.MAGIC), 0, FrameFileWriter.MAGIC.length)) {\n          streamPart = StreamPart.FRAMES;\n          deleteFromQueuedChunks(FrameFileWriter.MAGIC.length);\n        } else {\n          throw new ISE(\"Invalid stream header (id = %s, position = %d)\", id, bytesAdded - bytesBuffered);\n        }\n      }\n    }\n\n    if (streamPart == StreamPart.FRAMES) {\n      if (bytesBuffered >= Byte.BYTES) {\n        final Memory memory = copyFromQueuedChunks(1);\n        final byte markerByte = memory.getByte(0);\n\n        if (markerByte == FrameFileWriter.MARKER_FRAME || markerByte == FrameFileWriter.MARKER_RAC) {\n          // Read nextFrameLength if needed; otherwise do nothing.\n          // Both MARKER_FRAME and MARKER_RAC use the same compression envelope format.\n          final int bytesRequiredToReadLength = FRAME_MARKER_BYTES + FrameCompression.COMPRESSED_DATA_HEADER_SIZE;\n\n          if (nextCompressedFrameLength == UNKNOWN_LENGTH && bytesBuffered >= bytesRequiredToReadLength) {\n            nextMarkerType = markerByte;\n            nextCompressedFrameLength = copyFromQueuedChunks(bytesRequiredToReadLength)\n                .getLong(FRAME_MARKER_BYTES + Byte.BYTES /* Compression strategy byte */);","sourceCodeStart":388,"sourceCodeEnd":424,"githubUrl":"https://github.com/apache/druid/blob/9b90983fd291f26935af934383ce360473179e4d/processing/src/main/java/org/apache/druid/frame/channel/ReadableByteChunksFrameChannel.java#L388-L424","documentation":"The channel expects a stream to begin with FrameFileWriter.MAGIC. If the first bytes buffered do not equal that magic, the stream is not a valid frame stream, so updateStreamState throws with the channel id and stream position. This detects reading a non-frame file or garbage stream.","triggerScenarios":"addChunk()/nextRAC() triggering updateStreamState while streamPart is HEADER and the first FrameFileWriter.MAGIC.length bytes do not match MAGIC.","commonSituations":"Pointing the channel at the wrong file (not a frame file); reading a partially written/zero-length file; version mismatch where the writer format changed; corrupted first block on disk.","solutions":["Verify the file/channel source is actually a frame file written by FrameFileWriter.","Check that the writer fully completed before the reader started (await writer completion).","Ensure both sides run compatible Druid versions.","Regenerate the data and check storage integrity."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"if (!frameFile.exists() || frameFile.length() < FrameFileWriter.MAGIC.length) { throw new IllegalStateException(\"not a frame file: \" + file); }","typeGuard":null,"tryCatchPattern":"try { rac = channel.read(); } catch (ISE e) { if (e.getMessage().startsWith(\"Invalid stream header\")) { failStage(\"source is not a frame stream\", e); } else { throw e; } }","preventionTips":["Only pass files created by FrameFileWriter to frame channels.","Await writer completion before opening the channel.","Check the first bytes for MAGIC when unsure of a file's provenance."],"tags":["druid","frame-channel","corruption"],"backgroundTag":"invalid-argument-format","analyzedSha":"9b90983fd291f26935af934383ce360473179e4d","analyzedAt":"2026-09-07T13:32:30.957Z","contentChangedAt":"2026-09-07T13:32:30.957Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}