What causes "Invalid trailing characters." in oracle/graal?

Fix the signature string to be exactly one method descriptor: '( ) ' with nothing after the return type, e.g. '(II)I'.

oracle/graal · error · RuntimeException

Invalid trailing characters.

Error message

Invalid trailing characters.

What it means

APHotSpotSignature parses a JVM method signature string such as '(II)V'. After matching the argument list in parentheses and one return-type descriptor, if characters remain the constructor throws RuntimeException('Invalid trailing characters.'). This guards against malformed signatures with garbage after the return type — typically a closing paren issue, duplicated return types, or a truncated/concatenated signature string.

Source

Thrown at compiler/src/jdk.graal.compiler.processor/src/jdk/graal/compiler/replacements/processor/APHotSpotSignature.java:64

    private TypeMirror returnTypeCache;

    APHotSpotSignature(String signature) {
        assert signature.length() > 0;
        this.originalString = signature;

        if (signature.charAt(0) == '(') {
            int cur = 1;
            while (cur < signature.length() && signature.charAt(cur) != ')') {
                int nextCur = parseSignature(signature, cur);
                arguments.add(signature.substring(cur, nextCur));
                cur = nextCur;
            }

            cur++;
            int nextCur = parseSignature(signature, cur);
            returnType = signature.substring(cur, nextCur);
            if (nextCur != signature.length()) {
                throw new RuntimeException("Invalid trailing characters.");
            }
        } else {
            returnType = null;
        }
    }

    private static int parseSignature(String signature, int start) {
        int cur = start;
        char first;
        do {
            first = signature.charAt(cur++);
        } while (first == '[');

        switch (first) {
            case 'L':
                while (signature.charAt(cur) != ';') {
                    cur++;
                }

View on GitHub (pinned to a66e9ccd1d)

Solutions

Fix the signature string to be exactly one method descriptor: '(<params>)<returnType>' with nothing after the return type, e.g. '(II)I'.
If building the descriptor in code, use a StringBuilder that stops after the return type and assert the final string matches the expected shape.
Validate candidate signatures against a regex or java.lang.invoke.MethodType.fromMethodDescriptorString before passing them in.
Re-run the annotation processing/build to confirm the processor accepts the signature.

Example fix

// before
new APHotSpotSignature("(II)VI"); // trailing 'I' after return type

// after
new APHotSpotSignature("(II)I");

Defensive patterns

Strategy: validation

Validate before calling

static boolean isWellFormedSignature(String sig) {
    return sig != null && sig.matches("\\((?:\\[*(?:[VIBCDFJSZ]|L[^;]+;))*\\)[VIBCDFJSZ]|L[^;]+;|\\[+[VIBCDFJSZ]");
}

// or delegate to the JDK parser:
try {
    MethodType.fromMethodDescriptorString(sig, ClassLoader.getSystemClassLoader());
    return true;
} catch (IllegalArgumentException | TypeNotPresentException e) {
    return false;
}

Try / catch

try {
    new APHotSpotSignature(descriptor);
} catch (RuntimeException e) {
    if (e.getMessage() != null && e.getMessage().contains("trailing")) {
        // descriptor has text after the return type: fix the source string
    }
    throw e;
}

Prevention

Build descriptors programmatically with MethodType.toMethodDescriptorString() instead of hand-writing them.
A method descriptor is exactly one '(...)' group followed by one return type — nothing after it.
Cross-check hand-written signatures against javap -s output for the target method.

When it happens

Trigger: Constructing APHotSpotSignature with a string like '(I)VI', '()V extra' or '(I)' where parsing the return type ends before the end of the string: after parseSignature for the return type, nextCur != signature.length() (APHotSpotSignature.java:60-66). Happens when @MethodParameter/@Signature-style annotation values or manually built descriptor strings are malformed.

Common situations: Hand-written signature strings in method-substitution annotations (extra characters, missing return type then trailing text); concatenating descriptors programmatically and forgetting to stop; copy-paste from javap output including comments/flags after the descriptor.

Related errors

AI-assisted analysis of oracle/graal@a66e9ccd1d (2026-08-14). Data as JSON: /api/errors/38d918f00ad75a45. Report an issue: GitHub.