alibaba/ARouter · error · HandlerException

LogisticsCenterFatal exception when loading group meta. [<fa

Error message

LogisticsCenterFatal exception when loading group meta. [<failure>]

What it means

hasRoute() checks whether a postcard's path can be resolved; if the route is not yet in Warehouse.routes it triggers addRouteGroupDynamic() to lazily load the group meta. Any exception from that lazy load is wrapped in a HandlerException tagged 'Fatal exception when loading group meta'.

Source

Thrown at arouter-api/src/main/java/com/alibaba/android/arouter/core/LogisticsCenter.java:258

    public synchronized static boolean hasRoute(Postcard postcard) {
        if (null == postcard
                || TextUtils.isEmpty(postcard.getPath())
                || TextUtils.isEmpty(postcard.getGroup())) {
            return false;
        }

        if (Warehouse.routes.containsKey(postcard.getPath())) {
            return true;
        }

        if (!Warehouse.groupsIndex.containsKey(postcard.getGroup())) {
            return false;
        }

        try {
            addRouteGroupDynamic(postcard.getGroup(), null);
        } catch (Exception e) {
            throw new HandlerException(
                    TAG + "Fatal exception when loading group meta. [" + describeFailure(e) + "]",
                    e
            );
        }

        return Warehouse.routes.containsKey(postcard.getPath());
    }

    /**
     * Completion the postcard by route metas
     *
     * @param postcard Incomplete postcard, should complete by this method.
     */
    public synchronized static void completion(Postcard postcard) {
        if (null == postcard) {
            throw new NoRouteFoundException(TAG + "No postcard!");
        }

View on GitHub (pinned to 84f451d244)

Solutions

1. Read the cause inside [<failure>] and fix the root exception (missing class, duplicate route, etc.)
2. Add keep rules for com.alibaba.android.arouter.routes.** in release builds
3. Run gradle clean and rebuild so generated group classes match current @Route declarations
4. Verify the module containing the route is an actual runtime dependency of the app

Example fix

// before
boolean ok = ARouter.getInstance().hasRoute(path); // crashes on unloadable group
// after
boolean ok;
try {
    ok = ARouter.getInstance().build(path).exist();
} catch (HandlerException e) {
    logger.warn(TAG, "route check failed", e);
    ok = false;
}

String group = path.split("/")[1];
if (!WarehouseGroupsKnown.contains(group) && !path.startsWith("/app/")) {
    Log.w(TAG, "group " + group + " may not be registered");
}

try {
    exists = postcard.exist();
} catch (HandlerException e) {
    Log.w(TAG, "group meta load failed for path", e);
    exists = false; // treat as route-not-available
}

When it happens

Trigger: Calling ARouter's hasRoute/exist check for a path whose group class cannot be loaded — generated group class missing, ClassNotFoundException, or duplicate-key RuntimeException during dynamic group registration.

Common situations: Querying a route from a module whose generated ARouter$$Group class was stripped by R8; checking existence of a path registered by a module that was removed; stale build artifacts after renaming routes.

Related errors

• LogisticsCenterARouter init logistics center exception! [<fa
• String.format(tipText, key)
• Interceptor timeout has already been scheduled.
• Interceptor initialization failure must have a cause.
• TimeUnit must not be null.

AI-assisted analysis of alibaba/ARouter@84f451d244 (2026-09-06). Data as JSON: /api/errors/847d283f9aa98d9f. Report an issue: GitHub.