oracle/graal · error · IllegalArgumentException

@CompilationFinal(dimensions=%d) exceeds declared array dime

Error message

@CompilationFinal(dimensions=%d) exceeds declared array dimensions (%d) of field %s

What it means

The second @CompilationFinal validation in actualStableDimensions: for a non-negative dimensions value, it counts the array dimensions of the field's declared type (getArrayDimensions) and throws IllegalArgumentException when dimensions exceeds that count. The annotation claims more stable array levels than the field's type actually has.

Source

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

        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
     *            {@code types} to its underlying host {@link ResolvedJavaType}. In native-image,
     *            known Truffle types are represented as {@code AnalysisType}, while the keys in
     *            {@code declaredAnnotationValues} correspond to host JVMCI types. Therefore, each
     *            {@code AnalysisType} must be unwrapped via
     *            {@code OriginalClassProvider.getOriginalType(JavaType)} to correctly access the

View on GitHub (pinned to a66e9ccd1d)

Solutions

1. Lower dimensions to at most the array depth of the field's type (0 for scalar fields, which means the reference itself is stable).
2. Or change the field type to an array with at least that many dimensions if deeper stability was intended.

Example fix

// before
@CompilationFinal(dimensions = 2)
Object[] values; // only 1 array dimension

// after
@CompilationFinal(dimensions = 1)
Object[] values;

// Mirror the compiler's check: annotation dimensions must not exceed the field's array depth
static void checkCompilationFinal(Class<?> owner, String fieldName, int dimensions) throws NoSuchFieldException {
    Class<?> t = owner.getDeclaredField(fieldName).getType();
    int arrayDim = 0;
    while (t.isArray()) { arrayDim++; t = t.getComponentType(); }
    if (dimensions < -1 || (dimensions >= 0 && dimensions > arrayDim)) {
        throw new IllegalArgumentException(owner.getName() + "." + fieldName
                + ": dimensions=" + dimensions + " exceeds array depth " + arrayDim);
    }
}

When it happens

Trigger: @CompilationFinal(dimensions = 2) on a field of type Object[] (1 dimension), or any positive dimensions on a non-array field.

Common situations: Changing a field's type from Object[][] to Object[] or to a scalar without updating the annotation; copy-pasting an annotated field declaration and changing only the type.

Related errors

• Negative @CompilationFinal dimensions
• Cannot find partial evaluation configuration: %s
• Invalid option
• Unknown tier option value '%s'. %s
• The "%s" is not a valid performance warning kind. Valid valu

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