quarkusio/quarkus · error · RuntimeException

Invalid lightness, number needs to be between 0 and 100. 0%

Error message

Invalid lightness, number needs to be between 0 and 100. 0% is black, 50% is normal, and 100% is white

What it means

The BuildTimeContentProcessor.Color record validates the HSL color components used to generate per-extension Dev UI theme colors. This error is thrown by the Color constructor when the lightness is outside 0–100, since lightness is a percentage (0 = black, 50 = normal, 100 = white).

Source

Thrown at extensions/devui/deployment/src/main/java/io/quarkus/devui/deployment/BuildTimeContentProcessor.java:1341

        private int saturation; // Defines the saturation; 0% is a shade of gray and 100% is the full color (full saturation)
        private int lightness; // Defines the lightness; 0% is black, 50% is normal, and 100% is white
        private double alpha; // Defines the opacity; 0 is fully transparent, 100 is not transparent at all

        private Color(int hue, int saturation, int lightness, double alpha) {
            if (hue < 0 || hue > 360) {
                throw new RuntimeException(
                        "Invalid hue, number needs to be between 0 and 360. Defines a degree on the color wheel");
            }
            this.hue = hue;

            if (saturation < 0 || saturation > 100) {
                throw new RuntimeException(
                        "Invalid saturation, number needs to be between 0 and 100. 0% is a shade of gray and 100% is the full color (full saturation)");
            }
            this.saturation = saturation;

            if (lightness < 0 || lightness > 100) {
                throw new RuntimeException(
                        "Invalid lightness, number needs to be between 0 and 100. 0% is black, 50% is normal, and 100% is white");
            }
            this.lightness = lightness;

            if (alpha < 0 || alpha > 1) {
                throw new RuntimeException(
                        "Invalid alpha, number needs to be between 0 and 1. 0 is fully transparent, 1 is not transparent at all");
            }
            this.alpha = alpha;
        }

        @Override
        public String toString() {
            return "hsla(" + this.hue + ", " + this.saturation + "%, " + this.lightness + "%, " + this.alpha + ")";
        }

        static Color from(Color color, double alpha) {
            return new Color(color.hue, color.saturation, color.lightness, alpha);

View on GitHub (pinned to e1c734241f)

Solutions

1. Scale 0–1 lightness to percent: lightness = Math.round(l01 * 100)
2. Clamp with Math.max(0, Math.min(100, lightness)) before constructing the Color
3. Fix the hardcoded or computed value to lie within 0–100

Example fix

// before
Color c = new Color(210, 60, 0.5, 1.0); // 0.5 is 0-1 scale
// after
Color c = new Color(210, 60, (int) Math.round(0.5 * 100), 1.0);

int l = (int) Math.round(light01 * 100); // convert 0-1 to percent
if (l < 0 || l > 100) throw new IllegalArgumentException("lightness must be 0-100");

boolean isValidLightness(int l) { return l >= 0 && l <= 100; }

try {
    Color c = new Color(hue, sat, light, alpha);
} catch (RuntimeException e) {
    if (e.getMessage().startsWith("Invalid lightness")) {
        c = new Color(hue, sat, Math.max(0, Math.min(100, light)), alpha);
    } else throw e;
}

When it happens

Trigger: Constructing a Color with a negative lightness or lightness greater than 100 during build-time Dev UI content generation.

Common situations: A custom extension passing an 0–1 lightness value without converting to percent; CSS-style lightness strings parsed as floats and mis-scaled; typo in a hardcoded theme value.

Related errors

• Invalid hue, number needs to be between 0 and 360. Defines a
• Invalid saturation, number needs to be between 0 and 100. 0%
• Invalid alpha, number needs to be between 0 and 1. 0 is full
• An error occurred while processing ${resourceName}
• Failed to read ${extPropsVisitUrl}

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/bba651c8dbd53954. Report an issue: GitHub.