What causes "Matrix cannot be null" in Baseflow/PhotoView?

Check for null before calling: if (matrix != null) photoView.setDisplayMatrix(matrix);

Baseflow/PhotoView · error · IllegalArgumentException

Matrix cannot be null

Error message

Matrix cannot be null

What it means

PhotoView's setDisplayMatrix(RectF/Matrix) API rejects a null Matrix argument immediately with an IllegalArgumentException. The attacher needs a real Matrix to copy into its supplementary matrix (mSuppMatrix.set(finalMatrix)) so it can recompute and constrain the image display rect. Passing null would corrupt the zoom/drag state, so the library fails fast at the API boundary.

Source

Thrown at photoview/src/main/java/com/github/chrisbanes/photoview/PhotoViewAttacher.java:281

    }

    public void setOnSingleFlingListener(OnSingleFlingListener onSingleFlingListener) {
        this.mSingleFlingListener = onSingleFlingListener;
    }

    @Deprecated
    public boolean isZoomEnabled() {
        return mZoomEnabled;
    }

    public RectF getDisplayRect() {
        checkMatrixBounds();
        return getDisplayRect(getDrawMatrix());
    }

    public boolean setDisplayMatrix(Matrix finalMatrix) {
        if (finalMatrix == null) {
            throw new IllegalArgumentException("Matrix cannot be null");
        }
        if (mImageView.getDrawable() == null) {
            return false;
        }
        mSuppMatrix.set(finalMatrix);
        checkAndDisplayMatrix();
        return true;
    }

    public void setBaseRotation(final float degrees) {
        mBaseRotation = degrees % 360;
        update();
        setRotationBy(mBaseRotation);
        checkAndDisplayMatrix();
    }

    public void setRotationTo(float degrees) {
        mSuppMatrix.setRotate(degrees % 360);

View on GitHub (pinned to 565505d5cb)

Solutions

Check for null before calling: if (matrix != null) photoView.setDisplayMatrix(matrix);
If restoring from a saved state, default to a fresh matrix: photoView.setDisplayMatrix(savedMatrix != null ? savedMatrix : new Matrix());
Verify the code path that produces the matrix (getDisplayMatrix(new Matrix()) returns a copy; it never returns null when given an initialized Matrix) and fix the producer so it cannot emit null.

Example fix

// before
photoView.setDisplayMatrix(restoredMatrix);

// after
if (restoredMatrix != null) {
    photoView.setDisplayMatrix(restoredMatrix);
}

Defensive patterns

Strategy: validation

Validate before calling

Matrix m = restoreZoomMatrix(savedInstanceState);
if (m != null) {
    photoView.setDisplayMatrix(m);
}

Prevention

Treat Matrix as non-nullable in your API: annotate the parameter @NonNull and let the compiler warn.
Default null matrix sources to new Matrix() at the boundary where they enter (bundle restore, config objects).
Prefer the read-modify-write pattern: photoView.getDisplayMatrix(m); m.postScale(...); photoView.setDisplayMatrix(m); — the producer then can never be null.

When it happens

Trigger: Calling photoView.setDisplayMatrix(null) or PhotoViewAttacher.setDisplayMatrix(null) directly. Also happens indirectly when code builds a Matrix from getDisplayRect()/getDisplayMatrix() results that were never initialized, or when a matrix variable from a bundle/config is null and is forwarded without a check.

Common situations: Restoring a saved zoom state (e.g. from onSaveInstanceState where no matrix was saved yet), refactoring code that used to pass a new Matrix() but was 'simplified', or calling setDisplayMatrix before the view has any state in a ViewPager/RecyclerView holder where the matrix field is transient and null after reattachment.

Related errors

AI-assisted analysis of Baseflow/PhotoView@565505d5cb (2026-08-14). Data as JSON: /api/errors/b767a0a9512d201c. Report an issue: GitHub.