Tencent/QMUI_Android · error · IllegalArgumentException

Index conflicts with index used internally, please use negat

Error message

Index conflicts with index used internally, please use negative number for custom item

What it means

QMUISectionDiffCallback.appendCustomIndex throws an IllegalArgumentException when the computed offset (ITEM_INDEX_CUSTOM_OFFSET + itemIndex) is not recognized as a custom item index. This happens when itemIndex is too large (or mis-ranged), colliding with indexes the section framework uses internally for real items.

Source

Thrown at qmui/src/main/java/com/qmuiteam/qmui/widget/section/QMUISectionDiffCallback.java:286

        return (oldItem == null && newItem == null) ||
                (oldItem != null && newItem != null && oldItem.isSameContent(newItem));
    }

    public static class IndexGenerationInfo {
        private ArrayList<Integer> sectionIndexArray;
        private ArrayList<Integer> itemIndexArray;

        private IndexGenerationInfo(ArrayList<Integer> sectionIndex, ArrayList<Integer> itemIndex) {
            sectionIndexArray = sectionIndex;
            itemIndexArray = itemIndex;
        }

        public final void appendCustomIndex(int sectionIndex, int itemIndex) {

            int offset = QMUISection.ITEM_INDEX_CUSTOM_OFFSET + itemIndex;
            if(!QMUISection.isCustomItemIndex(offset)){
                throw new IllegalArgumentException(
                        "Index conflicts with index used internally, please use negative number for custom item");
            }
            appendIndex(sectionIndex, offset);
        }

        private void appendIndex(int sectionIndex, int itemIndex) {
            if (sectionIndex < 0) {
                throw new IllegalArgumentException("use appendWholeListCustomIndex for whole list");
            }
            sectionIndexArray.add(sectionIndex);
            itemIndexArray.add(itemIndex);
        }

        public final void appendWholeListCustomIndex(int itemIndex) {
            int offset = QMUISection.ITEM_INDEX_CUSTOM_OFFSET + itemIndex;
            if(!QMUISection.isCustomItemIndex(offset)){
                throw new IllegalArgumentException(
                        "Index conflicts with index used internally, please use negative number for custom item");

View on GitHub (pinned to 026e7d4866)

Solutions

Use a small custom item identifier (0-based within your custom set) so ITEM_INDEX_CUSTOM_OFFSET + itemIndex lands in the custom negative range.
Remove any extra offset you add yourself; the library already applies ITEM_INDEX_CUSTOM_OFFSET.
If you need whole-list custom entries, call appendWholeListCustomIndex instead.

Example fix

// before
callback.appendCustomIndex(sectionIndex, itemList.size()); // collides with internal indexes
// after
callback.appendCustomIndex(sectionIndex, 0); // small custom identifier for your custom row

Defensive patterns

Strategy: validation

Validate before calling

if (itemIndex >= 0 && QMUISection.isCustomItemIndex(QMUISection.ITEM_INDEX_CUSTOM_OFFSET + itemIndex)) {
    callback.appendCustomIndex(sectionIndex, itemIndex);
}

Try / catch

try {
    callback.appendCustomIndex(sectionIndex, itemIndex);
} catch (IllegalArgumentException e) {
    Log.e(TAG, "custom itemIndex out of custom range; use a small custom id", e);
}

Prevention

Use small, zero-based custom identifiers, not real list positions or sizes.
Never add your own offset — the library already applies ITEM_INDEX_CUSTOM_OFFSET.
Model custom items with a small enum or counter instead of positions.

When it happens

Trigger: Calling callback.appendCustomIndex(sectionIndex, itemIndex) with a non-negative or very large itemIndex such that offset no longer satisfies QMUISection.isCustomItemIndex(offset) — i.e. the custom index bleeds into the internal positive-index space.

Common situations: Passing an item position from the real list instead of a small custom identifier; computing a custom index by adding your own offset on top of the library's; custom index space exhausted because itemIndex exceeds the custom range.

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

AI-assisted analysis of Tencent/QMUI_Android@026e7d4866 (2026-09-06). Data as JSON: /api/errors/d25ed40c5fa320bc. Report an issue: GitHub.