airbnb/lottie-android · error · IllegalArgumentException

cache file must be a directory

Error message

cache file must be a directory

What it means

Thrown by the LottieNetworkCacheProvider created inside setNetworkCacheDir when getCacheDir() is invoked and File#isDirectory() returns false for the supplied file. This means the path either does not exist or exists as a regular file rather than a directory.

Source

Thrown at lottie/src/main/java/com/airbnb/lottie/LottieConfig.java:75

    public Builder setNetworkFetcher(@NonNull LottieNetworkFetcher fetcher) {
      this.networkFetcher = fetcher;
      return this;
    }

    /**
     * Provide your own network cache directory. By default, animations will be saved in your application's cacheDir/lottie_network_cache.
     *
     * @see #setNetworkCacheProvider(LottieNetworkCacheProvider)
     */
    @NonNull
    public Builder setNetworkCacheDir(@NonNull final File file) {
      if (cacheProvider != null) {
        throw new IllegalStateException("There is already a cache provider!");
      }
      cacheProvider = new LottieNetworkCacheProvider() {
        @Override @NonNull public File getCacheDir() {
          if (!file.isDirectory()) {
            throw new IllegalArgumentException("cache file must be a directory");
          }
          return file;
        }
      };
      return this;
    }

    /**
     * Provide your own network cache provider. By default, animations will be saved in your application's cacheDir/lottie_network_cache.
     */
    @NonNull
    public Builder setNetworkCacheProvider(@NonNull final LottieNetworkCacheProvider fileCacheProvider) {
      if (cacheProvider != null) {
        throw new IllegalStateException("There is already a cache provider!");
      }
      cacheProvider = new LottieNetworkCacheProvider() {
        @NonNull @Override public File getCacheDir() {
          File file = fileCacheProvider.getCacheDir();

View on GitHub (pinned to 05ea92e903)

Solutions

1. Before setNetworkCacheDir, create the directory: File dir = new File(getCacheDir(), "lottie_network_cache"); dir.mkdirs();
2. Verify the File refers to a folder, not a file name - append a sub-folder segment, not a filename.
3. If the path is occupied by a regular file, delete it or choose a different directory.
4. Call setNetworkCacheProvider instead and create the directory lazily inside the provider.

Example fix

// before
File cache = new File(context.getCacheDir(), "lottie_network_cache.dat");
LottieConfig.Builder().setNetworkCacheDir(cache); // .dat is a file

// after
File cache = new File(context.getCacheDir(), "lottie_network_cache");
cache.mkdirs();
LottieConfig.Builder().setNetworkCacheDir(cache);

File dir = new File(getCacheDir(), "lottie_network_cache");
if (!dir.exists() && !dir.mkdirs()) throw new IOException("cannot create cache dir");
if (!dir.isDirectory()) throw new IllegalStateException(dir + " is not a directory");
builder.setNetworkCacheDir(dir);

When it happens

Trigger: Passing a File to setNetworkCacheDir that points to a non-existent path or to an existing regular file; the directory not yet created on disk when the network cache first tries to write; a path collision where a file (not a folder) was already written at that location.

Common situations: Forgetting to call mkdirs() on a custom cache directory; pointing at context.getCacheDir() then appending a filename instead of a folder name; a previous run wrote a file at the intended directory path.

Related errors

• There is already a cache provider!
• lottie_rawRes and lottie_fileName cannot be used at the same
• You must set an images folder before loading an image. Set i
• You must provide a static value in the constructor , call se

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