youth5201314/banner · error · IllegalStateException

The layoutManager must be LinearLayoutManager

Error message

The layoutManager must be LinearLayoutManager

What it means

MarginDecoration (a RecyclerView ItemDecoration) only works when the RecyclerView's LayoutManager is a LinearLayoutManager (or subclass like GridLayoutManager). During getItemOffsets it calls requireLinearLayoutManager, which throws IllegalStateException if the LayoutManager is missing or of another type (e.g. StaggeredGridLayoutManager). This is a precondition check so the decoration can compute margins from the linear orientation.

Solutions

1. Call recyclerView.setLayoutManager(new LinearLayoutManager(context)) (or set orientation via BannerConfig) before adding MarginDecoration.
2. Remove MarginDecoration if you intentionally use a non-linear LayoutManager; it is not designed for it.
3. If wrapping a banner-internal RecyclerView, let the Banner manage its own LinearLayoutManager instead of replacing it.
4. Check that the LayoutManager is set before Layout/adapter attach, since parent.getLayoutManager() can be null early.

Example fix

// before
recyclerView.setLayoutManager(new StaggeredGridLayoutManager(2, StaggeredGridLayoutManager.VERTICAL));
recyclerView.addItemDecoration(new MarginDecoration(...)); // IllegalStateException
// after
recyclerView.setLayoutManager(new LinearLayoutManager(context, LinearLayoutManager.HORIZONTAL, false));
recyclerView.addItemDecoration(new MarginDecoration(...));

if (!(recyclerView.getLayoutManager() instanceof LinearLayoutManager)) {
    recyclerView.setLayoutManager(new LinearLayoutManager(context, LinearLayoutManager.HORIZONTAL, false));
}
recyclerView.addItemDecoration(new MarginDecoration(context));

RecyclerView.LayoutManager lm = recyclerView.getLayoutManager();
boolean ok = lm instanceof LinearLayoutManager;
LinearLayoutManager llm = ok ? (LinearLayoutManager) lm : null;

When it happens

Trigger: Attaching MarginDecoration (directly or via banner.setItemCountAndDecoration-style usage) to a RecyclerView whose LayoutManager is StaggeredGridLayoutManager, GridLayoutManager with a non-LinearLayoutManager cast path, a custom LayoutManager, or is null (no LayoutManager set on the RecyclerView).

Common situations: Using the banner/indicator with a custom RecyclerView setup and forgetting setLayoutManager; switching LayoutManager types after adding the decoration; applying the decoration to a generic RecyclerView rather than the banner's internal one; code migration where a Flexbox/StaggeredGrid layout replaced a LinearLayoutManager.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• getContext().getString(R.string.banner_adapter_null_error)
• Expected the page view to be managed by a ViewPager2…

AI-assisted analysis of youth5201314/banner@777c7dbfaa (2026-09-08). Data as JSON: /api/errors/09e56fe4e63cc450. Report an issue: GitHub.

Appendix: source

Thrown at banner/src/main/java/com/youth/banner/itemdecoration/MarginDecoration.java:39

    @Override
    public void getItemOffsets(@NonNull Rect outRect, @NonNull View view, @NonNull RecyclerView parent,
                               @NonNull RecyclerView.State state) {
        LinearLayoutManager linearLayoutManager = requireLinearLayoutManager(parent);
        if (linearLayoutManager.getOrientation() == LinearLayoutManager.VERTICAL) {
            outRect.top = mMarginPx;
            outRect.bottom = mMarginPx;
        } else {
            outRect.left = mMarginPx;
            outRect.right = mMarginPx;
        }
    }

    private LinearLayoutManager requireLinearLayoutManager(@NonNull RecyclerView parent) {
        RecyclerView.LayoutManager layoutManager = parent.getLayoutManager();
        if (layoutManager instanceof LinearLayoutManager) {
            return (LinearLayoutManager) layoutManager;
        }
        throw new IllegalStateException("The layoutManager must be LinearLayoutManager");
    }
}

View on GitHub (pinned to 777c7dbfaa)