Tencent/matrix · error · IllegalStateException

Expected node to have an exclusion

Error message

Expected node to have an exclusion

What it means

ShortestPathFinder.findPath processes nodes from toVisitQueue, or from toVisitIfNoPathQueue when the main queue is empty. Nodes in the fallback queue must carry an exclusion (they were enqueued as last-resort paths); if one has a null exclusion, an internal invariant of the path finder is broken and it throws IllegalStateException.

Solutions

  1. Create a fresh ShortestPathFinder for each findPath call (ensure clearState runs between searches).
  2. Update Matrix to the latest version where ShortestPathFinder invariants were fixed.
  3. Re-capture the hprof; a malformed dump can produce inconsistent reference nodes.
  4. Catch IllegalStateException around the analysis and report analysis failure rather than crashing the caller.

Example fix

// before
node = toVisitIfNoPathQueue.poll();
if (node.exclusion == null) {
    throw new IllegalStateException("Expected node to have an exclusion " + node);
}
// after
node = toVisitIfNoPathQueue.poll();
if (node == null) {
    break; // search exhausted
}
if (node.exclusion == null) {
    continue; // treat as normal node instead of failing the whole search
}
Defensive patterns

Strategy: try-catch

Validate before calling

// run one findPath per freshly constructed ShortestPathFinder instance

Try / catch

try { return finder.findPath(startObjects, targetRefs, excludeRefs); } catch (IllegalStateException e) { return analysisFailed(e); }

Prevention

When it happens

Trigger: findPath dequeues from toVisitIfNoPathQueue and finds node.exclusion == null — a node was enqueued into the no-path queue without an associated exclusion record, typically due to stale state after a previous search or an enqueue-logic bug.

Common situations: Reusing a ShortestPathFinder instance across multiple findPath calls without clearState; heap dumps with unusual reference graphs; Matrix/Haha parser versions with known graph-enqueue bugs.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

AI-assisted analysis of Tencent/matrix@3b8293bd65 (2026-09-08). Data as JSON: /api/errors/0f7b004111f6815d. Report an issue: GitHub.

Appendix: source

Thrown at matrix/matrix-android/matrix-resource-canary/matrix-resource-canary-analyzer/src/main/java/com/tencent/matrix/resource/analyzer/utils/ShortestPathFinder.java:259

        canIgnoreStrings = true;
        for (Instance targetReference : targetReferences) {
            if (isString(targetReference)) {
                canIgnoreStrings = false;
                break;
            }
        }

        final Set<Instance> targetRefSet = new HashSet<>(targetReferences);

        while (!toVisitQueue.isEmpty() || !toVisitIfNoPathQueue.isEmpty()) {
            ReferenceNode node;
            if (!toVisitQueue.isEmpty()) {
                node = toVisitQueue.poll();
            } else {
                node = toVisitIfNoPathQueue.poll();
                if (node.exclusion == null) {
                    throw new IllegalStateException("Expected node to have an exclusion " + node);
                }
            }

            // Termination
            if (targetRefSet.contains(node.instance)) {
                results.put(node.instance, new Result(node, node.exclusion != null));
                targetRefSet.remove(node.instance);
                if (targetRefSet.isEmpty()) {
                    break;
                }
            }

            if (checkSeen(node)) {
                continue;
            }

            if (node.instance instanceof RootObj) {
                visitRootObj(node);

View on GitHub (pinned to 3b8293bd65)