What causes "maxCacheSize must be a positive number" in nostra13/Android-Universal-Image-Loader?

Pass explicit positive bytes: diskCacheSize(50 * 1024 * 1024)

nostra13/Android-Universal-Image-Loader · error · IllegalArgumentException

maxCacheSize must be a positive number

Error message

maxCacheSize must be a positive number

What it means

ImageLoaderConfiguration.Builder.diskCacheSize(int) validates that the LruDiskCache byte cap is strictly positive; a zero or negative cap would make the disk LRU immediately evict everything. Setting this switches the disk cache implementation to LruDiskCache and logs a warning (WARNING_OVERLAP_DISK_CACHE_PARAMS) if you had already set a custom diskCache().

Source

Thrown at library/src/main/java/com/nostra13/universalimageloader/core/ImageLoaderConfiguration.java:426

			return this;
		}

		/** @deprecated Use {@link #diskCacheSize(int)} instead */
		@Deprecated
		public Builder discCacheSize(int maxCacheSize) {
			return diskCacheSize(maxCacheSize);
		}

		/**
		 * Sets maximum disk cache size for images (in bytes).<br />
		 * By default: disk cache is unlimited.<br />
		 * <b>NOTE:</b> If you use this method then
		 * {@link com.nostra13.universalimageloader.cache.disc.impl.ext.LruDiskCache LruDiskCache}
		 * will be used as disk cache. You can use {@link #diskCache(DiskCache)} method for introduction your own
		 * implementation of {@link DiskCache}
		 */
		public Builder diskCacheSize(int maxCacheSize) {
			if (maxCacheSize <= 0) throw new IllegalArgumentException("maxCacheSize must be a positive number");

			if (diskCache != null) {
				L.w(WARNING_OVERLAP_DISK_CACHE_PARAMS);
			}

			this.diskCacheSize = maxCacheSize;
			return this;
		}

		/** @deprecated Use {@link #diskCacheFileCount(int)} instead */
		@Deprecated
		public Builder discCacheFileCount(int maxFileCount) {
			return diskCacheFileCount(maxFileCount);
		}

		/**
		 * Sets maximum file count in disk cache directory.<br />
		 * By default: disk cache is unlimited.<br />

View on GitHub (pinned to ba33ec64d0)

Solutions

Pass explicit positive bytes: diskCacheSize(50 * 1024 * 1024)
To disable the disk cache, don't call diskCacheSize at all / don't configure a disk cache, rather than passing 0
Clamp dynamic values: Math.max(1, computedBytes)

Example fix

// before
long free = new StatFs(dir.getPath()).getAvailableBytes();
builder.diskCacheSize((int) (free * 0.1)); // 0 when free space misreported

// after
int bytes = (int) Math.max(10L * 1024 * 1024, free / 10);
builder.diskCacheSize(bytes);

Defensive patterns

Strategy: validation

Validate before calling

int bytes = Math.max(1, computedDiskCacheBytes);
builder.diskCacheSize(bytes);

Prevention

Do not use 0 to mean 'no disk cache' — omit the disk cache config instead
Clamp free-space-derived sizes to a sane floor (e.g. 10 MB)
Express disk sizes in bytes with explicit 1024*1024 factors

When it happens

Trigger: diskCacheSize(0) or negative; size computed from a config/free-space expression that returns 0 when storage is low; passing a megabyte count without the 1024*1024 multiplier during experiments.

Common situations: StatFs-based free-space calculations returning 0 on devices reporting unusual block sizes; A/B-flag-gated cache sizes where one branch is 0 ('cache disabled') instead of using no disk cache; remote config defaulting to 0.

Related errors

AI-assisted analysis of nostra13/Android-Universal-Image-Loader@ba33ec64d0 (2026-08-14). Data as JSON: /api/errors/7c6ee98db8ea350b. Report an issue: GitHub.