google/ExoPlayer · critical · FlacDecoderException

Failed to load decoder native libraries.

Error message

Failed to load decoder native libraries.

What it means

Thrown by the FlacDecoderJni constructor when FlacLibrary.isAvailable() returns false, i.e. the native libflac extension (libflacJNI.so) could not be loaded into the current process. The ExoPlayer FLAC extension is a thin Java wrapper over a native decoder compiled separately from the core library, so the JNI bridge must be present at runtime or every attempt to construct a decoder fails immediately.

Source

Thrown at extensions/flac/src/main/java/com/google/android/exoplayer2/ext/flac/FlacDecoderJni.java:64

    public FlacFrameDecodeException(String message, int errorCode) {
      super(message);
      this.errorCode = errorCode;
    }
  }

  private static final int TEMP_BUFFER_SIZE = 8192; // The same buffer size as libflac.

  private final long nativeDecoderContext;

  @Nullable private ByteBuffer byteBufferData;
  @Nullable private ExtractorInput extractorInput;
  @Nullable private byte[] tempBuffer;
  private boolean endOfExtractorInput;

  public FlacDecoderJni() throws FlacDecoderException {
    if (!FlacLibrary.isAvailable()) {
      throw new FlacDecoderException("Failed to load decoder native libraries.");
    }
    nativeDecoderContext = flacInit();
    if (nativeDecoderContext == 0) {
      throw new FlacDecoderException("Failed to initialize decoder");
    }
  }

  /**
   * Sets the data to be parsed.
   *
   * @param byteBufferData Source {@link ByteBuffer}.
   */
  public void setData(ByteBuffer byteBufferData) {
    this.byteBufferData = byteBufferData;
    this.extractorInput = null;
  }

  /**

View on GitHub (pinned to dd430f7053)

Solutions

1. Verify the FLAC extension native library is actually packaged: inspect the APK with the APK Analyzer for libflacJNI.so under lib/<abi>/ and confirm the abiFilters include the device's ABI.
2. If building from source, compile the FLAC extension following the extensions/flac README (set FLAC_EXTENSION_PATH, build libflac and the JNI wrapper with the NDK) and depend on the resulting AAR instead of the stub Java-only artifact.
3. Switch to Media3 (androidx.media3), which ships prebuilt decoder extensions including FLAC for all major ABIs, removing the custom NDK build step.
4. As a runtime fallback, exclude the FLAC renderer so playback routes to the platform/framework FLAC decoder (API 27+) via DefaultRenderersFactory setEnableDecoderFallback.

Example fix

// before
defaultRenderersFactory = new DefaultRenderersFactory(context); // FLAC renderer throws at first FLAC stream

// after
DefaultRenderersFactory factory = new DefaultRenderersFactory(context)
    .setEnableDecoderFallback(true); // fall back to platform FLAC decoder if extension missing

if (FlacLibrary.isAvailable()) {
  FlacDecoderJni jni = new FlacDecoderJni();
} else {
  // fall back to platform FLAC decoder or report unsupported
}

catch (FlacDecoderException e) { /* native libs missing: switch renderer, use platform decoder, or surface unsupported-format error */ }

When it happens

Trigger: Constructing FlacDecoderJni (directly, or indirectly via FlacAudioRenderer / FlacExtractor when a FLAC track is played) on a device where System.loadLibrary("flacJNI") failed: the .so is missing from the APK, the APK was built for the wrong ABI, or the extension was never compiled and linked into the media pipeline.

Common situations: Building ExoPlayer from source without running the extension build steps (the FLAC extension is not shipped in the default artifact); proguard/R8 stripping the native library; an ABI filter that excludes the shipped .so (e.g. arm64-only build run on an armeabi-v7a expectation, or an emulator with a mismatched ABI); using a Maven artifact that does not bundle the native FLAC binaries.

Related errors

• Failed to initialize decoder
• Failed to load decoder native libraries
• Error instantiating FLAC extension
• Error instantiating FFmpeg extension
• DECODER_QUERY_ERROR

AI-assisted analysis of google/ExoPlayer@dd430f7053 (2026-08-14). Data as JSON: /api/errors/0646f9a0efefc9f1. Report an issue: GitHub.