What causes "backtraceNum must be -1 or greater" in alibaba/arthas?

Pass -1 to disable backtrace capture, or a non-negative int to capture N backtraces.

alibaba/arthas · error · IllegalArgumentException

backtraceNum must be -1 or greater

Error message

backtraceNum must be -1 or greater

What it means

VmTool.referenceAnalyze(Class, int objectNum, int backtraceNum) rejects backtraceNum < -1. The value -1 is the documented sentinel meaning 'do not capture allocation backtraces'; any non-negative value requests that many backtraces per object. Values below -1 are invalid.

Source

Thrown at arthas-vmtool/src/main/java/arthas/VmTool.java:150

    }

    private static synchronized native int mallocTrim0();

    @Override
    public boolean mallocStats() {
        return mallocStats0();
    }
    private static synchronized native boolean mallocStats0();

    @Override
    public String heapAnalyze(int classNum, int objectNum) {
        return heapAnalyze0(classNum, objectNum);
    }

    @Override
    public String referenceAnalyze(Class<?> klass, int objectNum, int backtraceNum) {
        if (backtraceNum < -1) {
            throw new IllegalArgumentException("backtraceNum must be -1 or greater");
        }
        return referenceAnalyze0(klass, objectNum, backtraceNum);
    }
}

View on GitHub (pinned to 21cf2e9ba5)

Solutions

Pass -1 to disable backtrace capture, or a non-negative int to capture N backtraces.
Clamp the computed value: backtraceNum = Math.max(-1, value).
Validate user-supplied backtrace depth before calling.

Example fix

// before
String r = vmTool.referenceAnalyze(klass, objNum, depth - 1);  // depth == 0 -> -1 ok; depth negative -> throws

// after
int bt = Math.max(-1, depth - 1);
String r = vmTool.referenceAnalyze(klass, objNum, bt);

Defensive patterns

Strategy: validation

Validate before calling

int safeBt = Math.max(-1, backtraceNum);

Type guard

static boolean isValidBacktraceNum(int n) {
    return n >= -1;
}

Try / catch

try {
    return vmTool.referenceAnalyze(klass, objNum, bt);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("backtraceNum")) {
        return vmTool.referenceAnalyze(klass, objNum, -1);
    }
    throw e;
}

Prevention

Clamp backtraceNum with Math.max(-1, value) before calling.
Map 'disabled' flags to -1, never to a computed negative.
Document the -1 sentinel (no backtrace capture) in wrapper APIs.

When it happens

Trigger: Calling referenceAnalyze with a backtraceNum computed from user input or a subtraction that yields -2 or lower (e.g. depth - 1 where depth was 0).

Common situations: A 'disable backtraces' flag mapped to a negative sentinel via subtraction; an unset option defaulting to a negative number; off-by-one when clamping an upper bound.

Related errors

AI-assisted analysis of alibaba/arthas@21cf2e9ba5 (2026-08-14). Data as JSON: /api/errors/05b7a5ab1e83e7e8. Report an issue: GitHub.