What causes "not a inner api message. fallback to custom message" in Tencent/QMUI_Android?

Implement/verify your bridge handler's handleMessage(String, MessageFinishCallback) override handles the custom command.

Tencent/QMUI_Android · warning · RuntimeException

not a inner api message. fallback to custom message

Error message

not a inner api message. fallback to custom message

What it means

QMUIWebViewBridgeHandler.handleInnerMessage dispatches commands that QMUI treats as internal bridge APIs (currently only 'getSupportedCmdList'). Any other cmdName is not an inner API, so the handler throws a RuntimeException whose message tells the bridge to fall back to the custom message path (handleMessage). The exception is part of the internal routing: it is expected to propagate to the JS bridge layer, which catches it and forwards the message to the app's handleMessage.

Source

Thrown at qmui/src/main/java/com/qmuiteam/qmui/widget/webview/QMUIWebViewBridgeHandler.java:98

                                handleInnerMessage(cmdName, msgData, callback);
                            }catch (Throwable e){
                                handleMessage(msgDataOrigin, callback);
                            }
                        }
                    } catch (JSONException e) {
                        e.printStackTrace();
                    }
                }
            }
        });
    }


    private void handleInnerMessage(String cmdName, JSONObject jsonObject, MessageFinishCallback callback){
        if(MESSAGE_CMD_GET_SUPPORTED_CMD_LIST.equals(cmdName)){
            callback.finish(new JSONArray(getSupportedCmdList()));
        }else{
            throw new RuntimeException("not a inner api message. fallback to custom message");
        }
    }

    protected abstract List<String> getSupportedCmdList();

    protected abstract void handleMessage(String message, MessageFinishCallback callback);

    @Nullable
    public static String unescape(@Nullable String value) {
        if (value == null || value.isEmpty()) {
            return null;
        }
        String ret = value.substring(1, value.length() - 1)
                .replace("\\\\", "\\")
                .replace("\\\"", "\"");
        if ("null".equals(ret)) {
            return null;
        }

View on GitHub (pinned to 026e7d4866)

Solutions

Implement/verify your bridge handler's handleMessage(String, MessageFinishCallback) override handles the custom command.
If calling the handler yourself, catch RuntimeException around handleInnerMessage and fall back to handleMessage.
Use the exact inner command name (getSupportedCmdList) if you intended an inner API call.

Example fix

// before
handler.handleInnerMessage(cmd, json, callback); // throws for custom commands

// after
try {
    handler.handleInnerMessage(cmd, json, callback);
} catch (RuntimeException e) {
    handler.handleMessage(rawMessage, callback); // custom message path
}

Defensive patterns

Strategy: try-catch

Validate before calling

if ("getSupportedCmdList".equals(cmdName)) {
    handler.handleInnerMessage(cmdName, json, callback);
} else {
    handler.handleMessage(rawMessage, callback);
}

Try / catch

try {
    handler.handleInnerMessage(cmdName, json, callback);
} catch (RuntimeException e) {
    // expected for custom commands: route to the custom handler
    handler.handleMessage(rawMessage, callback);
}

Prevention

Understand this RuntimeException is the library's routing signal for custom messages, not a failure.
Always implement handleMessage in your bridge handler subclass.
Reserve the exact inner command names (e.g. getSupportedCmdList) and don't shadow them in handleMessage.

When it happens

Trigger: JavaScript calls postMessage/handleMessage with a cmdName other than MESSAGE_CMD_GET_SUPPORTED_CMD_LIST, so handleInnerMessage (invoked from onReceiveValue) falls into the else branch and throws — this is the normal path for app-defined commands.

Common situations: Seeing this exception in logs while using QMUIWebView's JS bridge; it looks alarming but is the designed signal to route non-inner messages to your handleMessage override. It becomes a real bug only if no fallback catching exists (e.g. using the handler outside QMUI's bridge plumbing).

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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