Tencent/QMUI_Android · error · IllegalStateException

customMatcher must implement interface QMUISchemeMatcher.

Error message

customMatcher must implement interface QMUISchemeMatcher.

What it means

SchemeProcessor.generateCustomMatcher validates that the customMatcher annotation value is a subtype of QMUISchemeMatcher. When it is not, the processor throws this IllegalStateException at compile time to prevent generating broken scheme-matching code.

Source

Thrown at arch-compiler/src/main/java/com/qmuiteam/qmui/arch/SchemeProcessor.java:361

                throw new IllegalStateException("customFactory must implement interface QMUISchemeIntentFactory.");
            }
        }else{
            if (!isSubtypeOfType(typeMirror, QMUISchemeFragmentFactoryType)) {
                throw new IllegalStateException("customFactory must implement interface QMUISchemeFragmentFactory.");
            }
        }

        return CodeBlock.of("$T.class", typeMirror);
    }

    private CodeBlock generateCustomMatcher(AnnotationMirror annotationMirror){
        AnnotationValue customFactory = getAnnotationValue(annotationMirror, "customMatcher");
        if (customFactory == null) {
            return CodeBlock.of("null");
        }
        TypeMirror typeMirror = (TypeMirror) customFactory.getValue();
        if (!isSubtypeOfType(typeMirror, QMUISchemeMatcherType)) {
            throw new IllegalStateException("customMatcher must implement interface QMUISchemeMatcher.");
        }

        return CodeBlock.of("$T.class", typeMirror);
    }

    private CodeBlock generateValueInterceptor(AnnotationMirror annotationMirror){
        AnnotationValue valueConverter = getAnnotationValue(annotationMirror, "valueConverter");
        if (valueConverter == null) {
            return CodeBlock.of("null");
        }
        TypeMirror typeMirror = (TypeMirror) valueConverter.getValue();
        if (!isSubtypeOfType(typeMirror, QMUISchemeValueConverterType)) {
            throw new IllegalStateException("customMatcher must implement interface QMUISchemeMatcher.");
        }

        return CodeBlock.of("$T.class", typeMirror);
    }

View on GitHub (pinned to 026e7d4866)

Solutions

Make the customMatcher class implement QMUISchemeMatcher (isScheme matches method).
Check the import refers to com.qmuiteam.qmui.arch.scheme.QMUISchemeMatcher.
Remove the customMatcher attribute if default matching is sufficient.

Example fix

// before
class MyMatcher { fun match(...) = true }

// after
class MyMatcher : QMUISchemeMatcher { override fun match(uri: Uri, action: String): Boolean = ... }

Defensive patterns

Strategy: validation

Validate before calling

fun validateMatcher(cls: Class<*>) =
    check(QMUISchemeMatcher::class.java.isAssignableFrom(cls)) { "${cls.name} must implement QMUISchemeMatcher" }

Type guard

fun isValidSchemeMatcher(cls: Class<*>): Boolean =
    QMUISchemeMatcher::class.java.isAssignableFrom(cls)

Prevention

Implement QMUISchemeMatcher on every class passed to customMatcher
Match the annotation field to the interface: customMatcher -> QMUISchemeMatcher only
Catch this at development time by building locally before pushing annotation changes

When it happens

Trigger: Setting customMatcher in a scheme annotation to a class that does not implement QMUISchemeMatcher.

Common situations: Passing an arbitrary class or a matcher written against an older QMUI API; refactored matcher lost the interface; copy-paste of a converter class into the matcher field.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

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