{"record":{"id":"7cf7ddf1fa3aa205","repo":"libgdx/libgdx","slug":"error-reading-initial-header-packet-7cf7dd","errorCode":null,"errorMessage":"Error reading initial header packet.","messagePattern":"Error reading initial header packet\\.","errorType":"exception","errorClass":"GdxRuntimeException","httpStatus":null,"severity":"error","filePath":"backends/gdx-backend-lwjgl3/src/com/badlogic/gdx/backends/lwjgl3/audio/OggInputStream.java","lineNumber":214,"sourceCode":"\n\t\t// extract the initial header from the first page and verify that the\n\t\t// Ogg bitstream is in fact Vorbis data\n\n\t\t// I handle the initial header first instead of just having the code\n\t\t// read all three Vorbis headers at once because reading the initial\n\t\t// header is an easy way to identify a Vorbis bitstream and it's\n\t\t// useful to see that functionality separated out.\n\n\t\toggInfo.init();\n\t\tcomment.init();\n\t\tif (streamState.pagein(page) < 0) {\n\t\t\t// error; stream version mismatch perhaps\n\t\t\tthrow new GdxRuntimeException(\"Error reading first page of Ogg bitstream.\");\n\t\t}\n\n\t\tif (streamState.packetout(packet) != 1) {\n\t\t\t// no page? must not be vorbis\n\t\t\tthrow new GdxRuntimeException(\"Error reading initial header packet.\");\n\t\t}\n\n\t\tif (oggInfo.synthesis_headerin(comment, packet) < 0) {\n\t\t\t// error case; not a vorbis header\n\t\t\tthrow new GdxRuntimeException(\"Ogg bitstream does not contain Vorbis audio data.\");\n\t\t}\n\n\t\t// At this point, we're sure we're Vorbis. We've set up the logical\n\t\t// (Ogg) bitstream decoder. Get the comment and codebook headers and\n\t\t// set up the Vorbis decoder\n\n\t\t// The next two packets in order are the comment and codebook headers.\n\t\t// They're likely large and may span multiple pages. Thus we read\n\t\t// and submit data until we get our two packets, watching that no\n\t\t// pages are missing. If a page is missing, error out; losing a\n\t\t// header page is the only place where missing data is fatal. */\n\n\t\tint i = 0;","sourceCodeStart":196,"sourceCodeEnd":232,"githubUrl":"https://github.com/libgdx/libgdx/blob/97f40861878058087be0685ca167ddfde132134b/backends/gdx-backend-lwjgl3/src/com/badlogic/gdx/backends/lwjgl3/audio/OggInputStream.java#L196-L232","documentation":"Thrown when streamState.packetout(packet) does not return 1 after the first page was accepted. The decoder expected the first Vorbis header packet on that page but could not extract a complete, uncorrupted packet. The Ogg container framing worked but no valid initial packet came out.","triggerScenarios":"First Ogg page is truncated or its CRC/segment table is damaged so packetout returns 0 (incomplete) or -1 (corrupt); a stream where the first page contains zero complete packets; reading a .ogg through a stream implementation that returns short reads that the decoder mishandles.","commonSituations":"Files truncated at exactly a page boundary during download, assets corrupted by an editor or version-control text-mode mangling, or feeding a non-seekable/filtered stream that alters bytes.","solutions":["Verify integrity with 'ogginfo file.ogg' or 'ffprobe'; re-export if it reports errors.","Re-encode the asset: ffmpeg -i in.ogg -c:a libvorbis out.ogg.","If wrapping the stream yourself, ensure read() returns unmodified bytes and -1/0 semantics are standard."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"catch (GdxRuntimeException e) when message starts with \"Error reading initial header packet\" — treat asset as corrupt, fall back to silence or a placeholder sound and log the path.","preventionTips":["Run ogginfo in CI for all Ogg assets.","Avoid text-mode processing of audio files (e.g. filters that rewrite streams).","Store assets in source control as binaries."],"tags":["audio","ogg","vorbis","corruption","libgdx"],"backgroundTag":null,"analyzedSha":"97f40861878058087be0685ca167ddfde132134b","analyzedAt":"2026-08-14T10:52:53.492Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}