libgdx/libgdx · error · GdxRuntimeException

Error reading initial header packet.

Error message

Error reading initial header packet.

What it means

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.

Source

Thrown at backends/gdx-backend-lwjgl3/src/com/badlogic/gdx/backends/lwjgl3/audio/OggInputStream.java:214

		// extract the initial header from the first page and verify that the
		// Ogg bitstream is in fact Vorbis data

		// I handle the initial header first instead of just having the code
		// read all three Vorbis headers at once because reading the initial
		// header is an easy way to identify a Vorbis bitstream and it's
		// useful to see that functionality separated out.

		oggInfo.init();
		comment.init();
		if (streamState.pagein(page) < 0) {
			// error; stream version mismatch perhaps
			throw new GdxRuntimeException("Error reading first page of Ogg bitstream.");
		}

		if (streamState.packetout(packet) != 1) {
			// no page? must not be vorbis
			throw new GdxRuntimeException("Error reading initial header packet.");
		}

		if (oggInfo.synthesis_headerin(comment, packet) < 0) {
			// error case; not a vorbis header
			throw new GdxRuntimeException("Ogg bitstream does not contain Vorbis audio data.");
		}

		// At this point, we're sure we're Vorbis. We've set up the logical
		// (Ogg) bitstream decoder. Get the comment and codebook headers and
		// set up the Vorbis decoder

		// The next two packets in order are the comment and codebook headers.
		// They're likely large and may span multiple pages. Thus we read
		// and submit data until we get our two packets, watching that no
		// pages are missing. If a page is missing, error out; losing a
		// header page is the only place where missing data is fatal. */

		int i = 0;

View on GitHub (pinned to 97f4086187)

Solutions

1. Verify integrity with 'ogginfo file.ogg' or 'ffprobe'; re-export if it reports errors.
2. Re-encode the asset: ffmpeg -i in.ogg -c:a libvorbis out.ogg.
3. If wrapping the stream yourself, ensure read() returns unmodified bytes and -1/0 semantics are standard.

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Error reading first page of Ogg bitstream.
• Corrupt secondary header.
• Error reading first page of Ogg bitstream.
• Error reading initial header packet.
• Corrupt secondary header.

AI-assisted analysis of libgdx/libgdx@97f4086187 (2026-08-14). Data as JSON: /api/errors/7cf7ddf1fa3aa205. Report an issue: GitHub.