oracle/graal · error · IllegalArgumentException

Negative @CompilationFinal dimensions

Error message

Negative @CompilationFinal dimensions

What it means

PartialEvaluator.actualStableDimensions validates the dimensions attribute of Truffle's @CompilationFinal annotation. The value -1 is the sentinel meaning 'all array dimensions of the field'; any other negative value (dimensions < 0 && != -1) throws IllegalArgumentException('Negative @CompilationFinal dimensions').

Source

Thrown at compiler/src/jdk.graal.compiler/src/jdk/graal/compiler/truffle/PartialEvaluator.java:164

        lastTierDecodingPlugins.maybePrintIntrinsics(options);
    }

    private static int getArrayDimensions(JavaType type) {
        int dimensions = 0;
        for (JavaType componentType = type; componentType.isArray(); componentType = componentType.getComponentType()) {
            dimensions++;
        }
        return dimensions;
    }

    private static int actualStableDimensions(ResolvedJavaField field, int dimensions) {
        if (dimensions == 0) {
            return 0;
        }
        int arrayDim = getArrayDimensions(field.getType());
        if (dimensions < 0) {
            if (dimensions != -1) {
                throw new IllegalArgumentException("Negative @CompilationFinal dimensions");
            }
            return arrayDim;
        }
        if (dimensions > arrayDim) {
            throw new IllegalArgumentException(String.format("@CompilationFinal(dimensions=%d) exceeds declared array dimensions (%d) of field %s", dimensions, arrayDim, field));
        }
        return dimensions;
    }

    /**
     * Gets an object describing how a read of {@code field} can be constant folded based on Truffle
     * annotations.
     *
     * @param field the field for which to compute {@link ConstantFieldInfo}
     * @param declaredAnnotationValues a map of method annotations keyed by their declaring
     *            {@link ResolvedJavaType}
     * @param types cached types known to the Truffle compiler
     * @param unwrapType a function that unwraps a {@link ResolvedJavaType} obtained from

View on GitHub (pinned to a66e9ccd1d)

Solutions

1. Use dimensions = -1 for 'all dimensions', or a non-negative count.
2. If dimensions is computed, clamp/validate it to the range [-1, arrayDim] before applying the annotation.

Example fix

// before
@CompilationFinal(dimensions = -2)
Object[] cache;

// after
@CompilationFinal(dimensions = -1) // all dimensions treated as compilation-final
Object[] cache;

// Validate an annotation dimension value before it reaches the partial evaluator
static boolean validDimensions(int d) {
    return d == -1 || d >= 0;
}
if (!validDimensions(dimensions)) {
    throw new IllegalArgumentException("@CompilationFinal dimensions must be -1 or >= 0, got " + dimensions);
}

When it happens

Trigger: Declaring a field with @CompilationFinal(dimensions = -2) or any negative value other than the -1 sentinel.

Common situations: Hand-writing the annotation with an arithmetic expression that evaluates below -1; porting code where -1 was computed dynamically and the computation went below -1; misunderstanding that only -1 has special meaning.

Related errors

• @CompilationFinal(dimensions=%d) exceeds declared array dime
• A negative probability of {} is not allowed!
• Cannot find partial evaluation configuration: %s
• Invalid option
• Unknown tier option value '%s'. %s

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