libgdx/libgdx · error · IllegalArgumentException

extension cannot be null.

Error message

extension cannot be null.

What it means

A plain argument-contract IllegalArgumentException from OpenALLwjglAudio.registerSound(extension, soundClass): the extension key that maps a file type to an OpenALSound implementation must not be null, otherwise the registry map would contain an unusable null key. It fires before the map write.

Source

Thrown at backends/gdx-backend-lwjgl/src/com/badlogic/gdx/backends/lwjgl/audio/OpenALLwjglAudio.java:104

		idleSources = new IntArray(allSources);
		soundIdToSource = new LongMap<>();
		sourceToSoundId = new IntMap<>();

		FloatBuffer orientation = BufferUtils.createFloatBuffer(6).put(new float[] {0.0f, 0.0f, -1.0f, 0.0f, 1.0f, 0.0f});
		((Buffer)orientation).flip();
		alListener(AL_ORIENTATION, orientation);
		FloatBuffer velocity = BufferUtils.createFloatBuffer(3).put(new float[] {0.0f, 0.0f, 0.0f});
		((Buffer)velocity).flip();
		alListener(AL_VELOCITY, velocity);
		FloatBuffer position = BufferUtils.createFloatBuffer(3).put(new float[] {0.0f, 0.0f, 0.0f});
		((Buffer)position).flip();
		alListener(AL_POSITION, position);

		recentSounds = new OpenALSound[simultaneousSources];
	}

	public void registerSound (String extension, Class<? extends OpenALSound> soundClass) {
		if (extension == null) throw new IllegalArgumentException("extension cannot be null.");
		if (soundClass == null) throw new IllegalArgumentException("soundClass cannot be null.");
		extensionToSoundClass.put(extension, soundClass);
	}

	public void registerMusic (String extension, Class<? extends OpenALMusic> musicClass) {
		if (extension == null) throw new IllegalArgumentException("extension cannot be null.");
		if (musicClass == null) throw new IllegalArgumentException("musicClass cannot be null.");
		extensionToMusicClass.put(extension, musicClass);
	}

	public OpenALSound newSound (FileHandle file) {
		String extension = file.extension().toLowerCase();
		return newSound(file, extension);
	}

	public OpenALSound newSound (FileHandle file, String extension) {
		if (file == null) throw new IllegalArgumentException("file cannot be null.");
		Class<? extends OpenALSound> soundClass = extensionToSoundClass.get(extension);

View on GitHub (pinned to 97f4086187)

Solutions

1. Pass a literal lowercase extension string: registerSound("ogg", Ogg.Sound.class).
2. Trace where the extension variable comes from and default it (e.g. from FileHandle.extension()) before registering.
3. Add a null/format check in your own registration helper so misconfiguration fails with a clearer message.

Example fix

// before
String ext = config.get("soundExt"); // null when key missing
audio.registerSound(ext, MySound.class);

// after
String ext = config.get("soundExt", "wav");
audio.registerSound(ext.toLowerCase(), MySound.class);

boolean validExtension(String ext) {
  return ext != null && ext.matches("[a-z0-9]+");
}

When it happens

Trigger: Calling audio.registerSound(null, Wav.Sound.class) — typically a variable that was supposed to hold a file extension ("ogg", "mp3", "wav") but was never assigned, or a lookup that returned null and was passed through unchecked.

Common situations: Custom backend extensions or asset pipelines that derive the extension at runtime (e.g. from a config entry) and pass a missing value; refactors that rename the extension constant leaving a null reference.

Related errors

• length cannot be < 0.
• file cannot be null.
• volume cannot be < 0:
• length cannot be < 0.
• extension cannot be null.

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