koral--/android-gif-drawable · error · IllegalStateException

Sample size out of range <1, 65535>

Error message

Sample size <sampleSize> out of range <1, 65535>

What it means

getDrawableAllocationByteCount estimates the memory a GifDrawable will need for its pixel buffer at a given sample size. The library validates that sampleSize is within <1, 65535> (Character.MAX_VALUE); anything outside that range cannot produce a valid downsampled bitmap, so it throws. Note the javadoc says IllegalArgumentException but the code actually throws IllegalStateException.

Solutions

1. Clamp sampleSize before calling: Math.max(1, Math.min(sampleSize, Character.MAX_VALUE))
2. Validate the source of the sample size (settings, division result) and default to 1 on invalid input
3. Catch IllegalStateException as a safety net and retry with sampleSize 1

Example fix

// before
long bytes = metadata.getDrawableAllocationByteCount(null, requestedSampleSize);
// after
int sampleSize = Math.max(1, Math.min(requestedSampleSize, Character.MAX_VALUE));
long bytes = metadata.getDrawableAllocationByteCount(null, sampleSize);

if (sampleSize < 1 || sampleSize > Character.MAX_VALUE) { throw new IllegalArgumentException("sampleSize out of range: " + sampleSize); }

boolean isValidSampleSize(int s) { return s >= 1 && s <= Character.MAX_VALUE; }

try { bytes = meta.getDrawableAllocationByteCount(null, sampleSize); } catch (IllegalStateException e) { bytes = meta.getDrawableAllocationByteCount(null, 1); }

When it happens

Trigger: Calling getDrawableAllocationByteCount(oldDrawable, sampleSize) with sampleSize < 1 or sampleSize > 65535, e.g. passing 0, a negative value from a failed calculation, or an unbounded user input.

Common situations: Computing sample size dynamically (e.g. from desired display size divided by intrinsic size) where a division yields 0 for very large desired sizes; user-configurable quality settings with no bounds checking; off-by-one when clamping.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• Position is not positive
• Bitmap is recycled
• Bitmap ia too small, size must be greater than or equal to…
• Only Config.ARGB_8888 is supported. Current bitmap config
• Frame index is not positive

AI-assisted analysis of koral--/android-gif-drawable@26ff795f78 (2026-09-10). Data as JSON: /api/errors/0e162725b99faf4a. Report an issue: GitHub.

Appendix: source

Thrown at android-gif-drawable/src/main/java/pl/droidsonroids/gif/GifAnimationMetaData.java:246

	 *
	 * @return possible size of the memory needed to store pixels excluding backing {@link android.graphics.Bitmap} and assuming no subsampling
	 */
	public long getAllocationByteCount() {
		return mPixelsBytesCount;
	}

	/**
	 * Like {@link #getAllocationByteCount()} but includes also backing {@link android.graphics.Bitmap} and takes sample size into account.
	 *
	 * @param oldDrawable optional old drawable to be reused, pass {@code null} if there is no one
	 * @param sampleSize  sample size, pass {@code 1} if not using subsampling
	 * @return possible size of the memory needed to store pixels
	 * @throws IllegalArgumentException if sample size out of range
	 */
	@Beta
	public long getDrawableAllocationByteCount(@Nullable GifDrawable oldDrawable, @IntRange(from = 1, to = Character.MAX_VALUE) int sampleSize) {
		if (sampleSize < 1 || sampleSize > Character.MAX_VALUE) {
			throw new IllegalStateException("Sample size " + sampleSize + " out of range <1, " + Character.MAX_VALUE + ">");
		}

		final int sampleSizeFactor = sampleSize * sampleSize;
		final long bufferSize;
		if (oldDrawable != null && !oldDrawable.mBuffer.isRecycled()) {
      bufferSize = oldDrawable.mBuffer.getAllocationByteCount();
    } else {
			bufferSize = (mWidth * mHeight * 4L) / sampleSizeFactor;
		}
		return (mPixelsBytesCount / sampleSizeFactor) + bufferSize;
	}

	/**
	 * See{@link GifDrawable#getMetadataAllocationByteCount()}
	 *
	 * @return maximum possible size of the allocated memory needed to store metadata
	 */
	public long getMetadataAllocationByteCount() {

View on GitHub (pinned to 26ff795f78)