Tencent/matrix · error · IllegalArgumentException

something wrong with trace, see detail log before

Error message

something wrong with trace, see detail log before

What it means

Thrown by MethodTracer.trace after tracing all class/jar inputs concurrently: if any trace worker set the traceError flag, the collected futures are awaited and then an IllegalArgumentException('something wrong with trace, see detail log before') is thrown. It aggregates a failure that occurred while instrumenting method bodies with Matrix's method-canary/trace bytecode transforms. The per-file stack trace was already logged before this aggregate exception.

Solutions

  1. Scroll up in the build log to find the per-class stack trace logged before this aggregate error — it names the failing class/jar
  2. Exclude the problematic class/package from tracing via the plugin's ignore/whiteList configuration
  3. Upgrade Matrix to the latest version to get fixes for known bytecode-handling issues
  4. Check compatibility between the Matrix plugin, AGP, and Gradle versions; downgrade/upgrade accordingly
Defensive patterns

Strategy: try-catch

Try / catch

try {
    methodTracer.trace(srcMap, jarList, classLoader, false)
} catch (IllegalArgumentException e) {
    logger.error('Matrix trace failed: inspect the per-class stack trace logged above for the failing class', e)
    throw e
}

Prevention

When it happens

Trigger: Any single .class or .jar entry fails bytecode transformation during traceMethodFromSrc/traceMethodFromJar — e.g. unexpected bytecode patterns, ASM visitor exceptions on obfuscated classes, or IO errors reading class files.

Common situations: Applying the Matrix trace plugin to modules with unusual bytecode (Kotlin coroutines, certain obfuscation by R8/ProGuard) or corrupted jar dependencies; version mismatch between AGP and the Matrix plugin's ASM version.

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/b83d77403b4dd6b8. Report an issue: GitHub.

Appendix: source

Thrown at matrix/matrix-android/matrix-gradle-plugin/src/main/java/com/tencent/matrix/trace/MethodTracer.java:91

    private volatile boolean traceError = false;

    public MethodTracer(ExecutorService executor, MappingCollector mappingCollector, Configuration config, ConcurrentHashMap<String, TraceMethod> collectedMap, ConcurrentHashMap<String, String> collectedClassExtendMap) {
        this.configuration = config;
        this.mappingCollector = mappingCollector;
        this.executor = executor;
        this.collectedClassExtendMap = collectedClassExtendMap;
        this.collectedMethodMap = collectedMap;
    }

    public void trace(Map<File, File> srcFolderList, Map<File, File> dependencyJarList, ClassLoader classLoader, boolean ignoreCheckClass) throws ExecutionException, InterruptedException {
        List<Future> futures = new LinkedList<>();
        traceMethodFromSrc(srcFolderList, futures, classLoader, ignoreCheckClass);
        traceMethodFromJar(dependencyJarList, futures, classLoader, ignoreCheckClass);
        for (Future future : futures) {
            future.get();
        }
        if (traceError) {
            throw new IllegalArgumentException("something wrong with trace, see detail log before");
        }
        futures.clear();
    }

    private void traceMethodFromSrc(Map<File, File> srcMap, List<Future> futures, final ClassLoader classLoader, final boolean skipCheckClass) {
        if (null != srcMap) {
            for (Map.Entry<File, File> entry : srcMap.entrySet()) {
                futures.add(executor.submit(new Runnable() {
                    @Override
                    public void run() {
                        innerTraceMethodFromSrc(entry.getKey(), entry.getValue(), classLoader, skipCheckClass);
                    }
                }));
            }
        }
    }

    private void traceMethodFromJar(Map<File, File> dependencyMap, List<Future> futures, final ClassLoader classLoader, final boolean skipCheckClass) {

View on GitHub (pinned to 3b8293bd65)