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

ImageAware should wrap ImageView. ImageViewAware is expected

Error message

ImageAware should wrap ImageView. ImageViewAware is expected.

What it means

CircleBitmapDisplayer.display() requires the ImageAware it receives to be an instance of ImageViewAware, because the resulting CircleDrawable is set via setImageDrawable on an ImageView-backed aware. The library throws IllegalArgumentException when any other ImageAware implementation (e.g. NonViewAware) is passed, since a circular clip only makes sense on a real ImageView target. This is a programming/configuration error, not a runtime data error.

Source

Thrown at library/src/main/java/com/nostra13/universalimageloader/core/display/CircleBitmapDisplayer.java:66

	protected final float strokeWidth;

	public CircleBitmapDisplayer() {
		this(null);
	}

	public CircleBitmapDisplayer(Integer strokeColor) {
		this(strokeColor, 0);
	}

	public CircleBitmapDisplayer(Integer strokeColor, float strokeWidth) {
		this.strokeColor = strokeColor;
		this.strokeWidth = strokeWidth;
	}

	@Override
	public void display(Bitmap bitmap, ImageAware imageAware, LoadedFrom loadedFrom) {
		if (!(imageAware instanceof ImageViewAware)) {
			throw new IllegalArgumentException("ImageAware should wrap ImageView. ImageViewAware is expected.");
		}

		imageAware.setImageDrawable(new CircleDrawable(bitmap, strokeColor, strokeWidth));
	}

	public static class CircleDrawable extends Drawable {

		protected float radius;

		protected final RectF mRect = new RectF();
		protected final RectF mBitmapRect;
		protected final BitmapShader bitmapShader;
		protected final Paint paint;
		protected final Paint strokePaint;
		protected final float strokeWidth;
		protected float strokeRadius;

		public CircleDrawable(Bitmap bitmap, Integer strokeColor, float strokeWidth) {

View on GitHub (pinned to ba33ec64d0)

Solutions

1. Pass an ImageViewAware (or just the ImageView itself — displayImage(ImageView, ...) wraps it automatically) when using CircleBitmapDisplayer
2. If you only need the processed bitmap (no view), remove the displayer from options and do the circular transformation yourself
3. If you target a non-View surface, implement a custom BitmapDisplayer that skips the instanceof check and consumes the bitmap directly

Example fix

// before
ImageAware aware = new NonViewAware(uri, new ImageSize(200, 200), ViewScaleType.CROP);
imageLoader.displayImage(uri, aware, new DisplayImageOptions.Builder()
        .displayer(new CircleBitmapDisplayer(Color.WHITE, 3))
        .build());

// after
ImageView imageView = (ImageView) findViewById(R.id.avatar);
imageLoader.displayImage(uri, imageView, new DisplayImageOptions.Builder()
        .displayer(new CircleBitmapDisplayer(Color.WHITE, 3))
        .build());

if (aware instanceof ImageViewAware) {
    imageLoader.displayImage(uri, aware, optionsWithCircleDisplayer);
} else {
    imageLoader.displayImage(uri, aware, optionsWithoutDisplayer);
}

private static boolean canDisplay(BitmapDisplayer d, ImageAware a) {
    return !(d instanceof CircleBitmapDisplayer) || a instanceof ImageViewAware;
}

When it happens

Trigger: Calling ImageLoader.displayImage(uri, aware, options) where options.displayer(new CircleBitmapDisplayer(...)) and 'aware' is a NonViewAware, a custom ImageAware, or any wrapper that does not extend ImageViewAware. Also occurs if you build your own ImageAware around a non-ImageView View and use this displayer.

Common situations: Developers migrating from Old Universal Image Loader samples where displayers were applied blindly; using NonViewAware to prefetch/process bitmaps while reusing display options configured for ImageView targets; passing a custom ImageAware for widget targets (e.g. RemoteViews-based) with a circle displayer attached.

Related errors

• ImageAware should wrap ImageView. ImageViewAware is expected
• ImageAware should wrap ImageView. ImageViewAware is expected
• URI [%1$s] doesn't have expected scheme [%2$s]
• ImageAware should wrap ImageView. ImageViewAware is expected
• cacheDir argument must be not null

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