What causes "must use the instance of QMUIWebViewClient" in Tencent/QMUI_Android?

Subclass QMUIWebViewClient instead of WebViewClient and pass that instance to setWebViewClient.

Tencent/QMUI_Android · error · IllegalArgumentException

must use the instance of QMUIWebViewClient

Error message

must use the instance of QMUIWebViewClient

What it means

QMUIWebView overrides setWebViewClient to enforce that only its own QMUIWebViewClient (or a subclass) is installed, because QMUI's internal features (load progress callbacks, bridge handling) rely on hooks inside QMUIWebViewClient. Passing any other WebViewClient is rejected with an IllegalArgumentException; null is still allowed.

Source

Thrown at qmui/src/main/java/com/qmuiteam/qmui/widget/webview/QMUIWebView.java:130

        mOnScrollChangeListeners.remove(listener);
    }

    public void removeAllOnScrollChangeListener(){
        mOnScrollChangeListeners.clear();
    }

    @Override
    protected void onScrollChanged(int l, int t, int oldl, int oldt) {
        super.onScrollChanged(l, t, oldl, oldt);
        for (OnScrollChangeListener onScrollListener : mOnScrollChangeListeners) {
            onScrollListener.onScrollChange(this, l, t, oldl, oldt);
        }
    }

    @Override
    public void setWebViewClient(WebViewClient client) {
        if (client != null && !(client instanceof QMUIWebViewClient)) {
            throw new IllegalArgumentException("must use the instance of QMUIWebViewClient");
        }
        super.setWebViewClient(client);
    }

    @Override
    public boolean dispatchKeyEvent(KeyEvent event) {
        return super.dispatchKeyEvent(event);
    }

    public void setNeedDispatchSafeAreaInset(boolean needDispatchSafeAreaInset) {
        if (mNeedDispatchSafeAreaInset != needDispatchSafeAreaInset) {
            mNeedDispatchSafeAreaInset = needDispatchSafeAreaInset;
            if (ViewCompat.isAttachedToWindow(this)) {
                if (needDispatchSafeAreaInset) {
                    ViewCompat.requestApplyInsets(this);
                } else {
                    // clear insets
                    setStyleDisplayCutoutSafeArea(new Rect());

View on GitHub (pinned to 026e7d4866)

Solutions

Subclass QMUIWebViewClient instead of WebViewClient and pass that instance to setWebViewClient.
Override the needed callbacks (shouldOverrideUrlLoading, onPageFinished, etc.) in your QMUIWebViewClient subclass.
If you do not need QMUIWebView's extensions, use a plain android.webkit.WebView instead.

Example fix

// before
webView.setWebViewClient(new WebViewClient() {
    @Override public boolean shouldOverrideUrlLoading(WebView v, String url) { return false; }
});

// after
webView.setWebViewClient(new QMUIWebViewClient(false, false) {
    @Override
    public boolean shouldOverrideUrlLoading(WebView v, String url) { return false; }
});

Defensive patterns

Strategy: type-guard

Validate before calling

if (client != null && !(client instanceof QMUIWebViewClient)) {
    throw new IllegalArgumentException("setWebViewClient requires a QMUIWebViewClient");
}

Type guard

// Java has no runtime narrowing sugar; use an explicit check helper
static boolean isValidClient(WebViewClient c) {
    return c == null || c instanceof QMUIWebViewClient;
}

Try / catch

try {
    webView.setWebViewClient(client);
} catch (IllegalArgumentException e) {
    webView.setWebViewClient(new QMUIWebViewClient(false, false));
}

Prevention

Always subclass QMUIWebViewClient for QMUIWebView instances.
Centralize webview setup in one factory so no plain WebViewClient can be installed.
Prefer using QMUIWebView's own client (it sets one internally) unless you need custom callbacks.

When it happens

Trigger: Calling webView.setWebViewClient(new WebViewClient(){...}) (or any non-QMUIWebViewClient instance, non-null) on a QMUIWebView instance.

Common situations: Migrating existing WebView code to QMUIWebView by copying over the standard Android setWebViewClient call; tutorials/snippets for android.webkit.WebView applied verbatim to QMUIWebView.

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

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