didi/DoKit · error · IllegalStateException

Could not find weak reference with key {} in {}

Error message

Could not find weak reference with key {} in {}

What it means

After finding the KeyedWeakReference class, findLeakingReference() scans its instances for one whose 'key' field equals the key passed to checkForLeak. If no instance matches, the watched reference is gone from the heap (already GC'd — which means no leak) or the key is wrong, and it throws IllegalStateException listing all keys it did find.

Source

Thrown at Android/dokit-leakcanary/src/main/java/com/squareup/leakcanary/HeapAnalyzer.java:244

        if (refClass == null) {
            throw new IllegalStateException(
                    "Could not find the " + KeyedWeakReference.class.getName() + " class in the heap dump.");
        }
        List<String> keysFound = new ArrayList<>();
        for (Instance instance : refClass.getInstancesList()) {
            List<ClassInstance.FieldValue> values = HahaHelper.classInstanceValues(instance);
            Object keyFieldValue = HahaHelper.fieldValue(values, "key");
            if (keyFieldValue == null) {
                keysFound.add(null);
                continue;
            }
            String keyCandidate = HahaHelper.asString(keyFieldValue);
            if (keyCandidate.equals(key)) {
                return HahaHelper.fieldValue(values, "referent");
            }
            keysFound.add(keyCandidate);
        }
        throw new IllegalStateException(
                "Could not find weak reference with key " + key + " in " + keysFound);
    }

    private AnalysisResult findLeakTrace(long analysisStartNanoTime, Snapshot snapshot,
                                         Instance leakingRef, boolean computeRetainedSize) {

        listener.onProgressUpdate(AnalyzerProgressListener.Step.FINDING_SHORTEST_PATH);
        ShortestPathFinder pathFinder = new ShortestPathFinder(excludedRefs);
        ShortestPathFinder.Result result = pathFinder.findPath(snapshot, leakingRef);

        String className = leakingRef.getClassObj().getClassName();

        // False alarm, no strong reference path to GC Roots.
        if (result.leakingNode == null) {
            return AnalysisResult.noLeak(className, since(analysisStartNanoTime));
        }

        listener.onProgressUpdate(AnalyzerProgressListener.Step.BUILDING_LEAK_TRACE);

View on GitHub (pinned to 626827cddb)

Solutions

1. Treat this exception as 'reference no longer in heap': catch IllegalStateException around checkForLeak and report it as no-leak rather than a crash
2. Make sure the heap dump is triggered while the KeyedWeakReference is still retained (LeakCanary's own flow retries after GC to avoid exactly this)
3. Verify the key string passed matches the one used in refWatcher.watch(reference, key)

Example fix

// before
AnalysisResult result = heapAnalyzer.checkForLeak(heapDumpFile, key);

// after
AnalysisResult result;
try {
  result = heapAnalyzer.checkForLeak(heapDumpFile, key);
} catch (IllegalStateException e) {
  // weak reference was cleared before dump -> object already GC'd, no leak
  result = AnalysisResult.noLeak("reference cleared", System.nanoTime());
}

try { result = heapAnalyzer.checkForLeak(heapDumpFile, key); } catch (IllegalStateException e) { if (e.getMessage().contains("Could not find weak reference")) { result = AnalysisResult.noLeak(...); } else throw e; }

When it happens

Trigger: Calling checkForLeak(heapDumpFile, key) where the weak reference with that key was cleared before the dump: the object was garbage collected (good news — no leak) so the KeyedWeakReference referent is null or the instance was collected. Also when passing a stale/wrong key, or when a heap dump is analyzed twice with a key from a different session.

Common situations: Analyzing a heap dump after the leaking object was already reclaimed. Keys mixed up between multiple dumps. Custom integrations that persist keys across app restarts and reuse them against fresh dumps.

Related errors

• Could not find char array in {}
• File does not exist: {}
• Could not find the {} class in the heap dump.
• leakTraceAsFakeException() can only be called when leakFound
• buildAndInstall() should only be called once.

AI-assisted analysis of didi/DoKit@626827cddb (2026-08-14). Data as JSON: /api/errors/5e881c9468cb0d3c. Report an issue: GitHub.