airbnb/lottie-android · error · IllegalStateException

You must set an images folder before loading an image. Set i

Error message

You must set an images folder before loading an image. Set it with LottieComposition#setImagesFolder or LottieDrawable#setImagesFolder

What it means

Thrown by ImageAssetManager when it tries to load an image asset referenced by the animation but imagesFolder is empty. Lottie animations can reference external bitmaps by filename; to resolve them from the app's assets, a folder prefix must be configured so the manager can open imagesFolder + filename.

Source

Thrown at lottie/src/main/java/com/airbnb/lottie/manager/ImageAssetManager.java:129

        bitmap = BitmapFactory.decodeByteArray(data, 0, data.length, opts);
      } catch (IllegalArgumentException e) {
        Logger.warning("Unable to decode image `" + id + "`.", e);
        return null;
      }

      if (bitmap == null) {
        Logger.warning("Decoded image `" + id + "` is null.");
        return null;
      }

      Bitmap resizedBitmap = Utils.resizeBitmapIfNeeded(bitmap, asset.getWidth(), asset.getHeight());
      return putBitmap(id, resizedBitmap);
    }

    InputStream is;
    try {
      if (TextUtils.isEmpty(imagesFolder)) {
        throw new IllegalStateException("You must set an images folder before loading an image." +
            " Set it with LottieComposition#setImagesFolder or LottieDrawable#setImagesFolder");
      }
      is = context.getAssets().open(imagesFolder + filename);
    } catch (IOException e) {
      Logger.warning("Unable to open asset.", e);
      return null;
    }

    try {
      bitmap = BitmapFactory.decodeStream(is, null, opts);
    } catch (IllegalArgumentException e) {
      Logger.warning("Unable to decode image `" + id + "`.", e);
      return null;
    }
    if (bitmap == null) {
      Logger.warning("Decoded image `" + id + "` is null.");
      return null;
    }

View on GitHub (pinned to 05ea92e903)

Solutions

1. Place the referenced images in an assets subfolder and call lottieDrawable.setImagesFolder("images/") (or composition.setImagesFolder) before playback.
2. If you supply bitmaps programmatically, register an ImageAssetDelegate via setImageAssetDelegate so the manager uses your bitmaps instead of the assets folder.
3. Confirm the folder string ends with a separator ("images/") since the manager concatenates imagesFolder + filename directly.
4. Verify each image's "p" filename in the JSON matches a file in that folder.

Example fix

// before
lottieAnimationView.setAnimation(R.anim.with_images);
lottieAnimationView.playAnimation(); // throws on first image asset

// after
lottieAnimationView.setAnimation(R.anim.with_images);
lottieAnimationView.setImageAssetsFolder("images/");
lottieAnimationView.playAnimation();

// Ensure the folder is set before any image-bearing animation plays
if (compositionHasImageAssets(lottieAnimationView.getComposition())) {
  lottieAnimationView.setImageAssetsFolder("images/");
}
boolean compositionHasImageAssets(LottieComposition c) {
  return c != null && c.getImages() != null && !c.getImages().isEmpty();
}

boolean needsImagesFolder(LottieComposition c) {
  return c != null && c.getImages() != null && !c.getImages().isEmpty();
}

When it happens

Trigger: Playing an animation whose JSON references image assets (an "assets" array with "p" filenames and an ImageAsset delegate) without first calling LottieComposition#setImagesFolder or LottieDrawable#setImagesFolder; or providing bitmaps via a custom ImageAssetDelegate but the manager still hits the folder-based fallback path.

Common situations: Loading a Lottie with embedded image references but forgetting to bundle/place the images in assets and set the folder; renaming the assets folder without updating the call; using a custom delegate that returns null for an id so the manager falls back to file loading.

Related errors

• Unable to parse composition
• lottie_rawRes and lottie_fileName cannot be used at the same
• There is already a cache provider!
• cache file must be a directory
• Cannot find marker with name {}.

AI-assisted analysis of airbnb/lottie-android@05ea92e903 (2026-08-14). Data as JSON: /api/errors/e7d32c9636d33586. Report an issue: GitHub.