quarkusio/quarkus · error · RuntimeException

Invalid hue, number needs to be between 0 and 360. Defines a

Error message

Invalid hue, number needs to be between 0 and 360. Defines a degree on the color wheel

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 hue is outside the 0–360 degree range, since hue is a degree on the color wheel and values outside it are not representable.

Source

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

            String defaultValue) {
        return theme.flatMap(themeModeExtractor) // Extract dark or light theme mode
                .flatMap(settingExtractor) // Extract specific setting
                .orElse(defaultValue); // Return default if not present
    }

    /**
     * This represents a HSLA color
     * see https://www.w3schools.com/html/html_colors_hsl.asp
     */
    static class Color {
        private int hue; // Defines a degree on the color wheel (from 0 to 360) - 0 (or 360) is red, 120 is green, 240 is blue
        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(

View on GitHub (pinned to e1c734241f)

Solutions

1. Normalize hue into range: hue = ((hue % 360) + 360) % 360 before constructing the Color
2. Clamp hue with Math.floorMod(hue, 360) or Math.min/max
3. Fix the source of the hue value (hash function, config default) to always produce 0–360

Example fix

// before
Color c = new Color(hueFromConfig, 60, 50, 1.0); // hue may be 540
// after
Color c = new Color(Math.floorMod(hueFromConfig, 360), 60, 50, 1.0);

int normalizedHue = Math.floorMod(hue, 360);
if (hue < 0 || hue > 360) throw new IllegalArgumentException("hue must be 0-360");

boolean isValidHue(int hue) { return hue >= 0 && hue <= 360; }

try {
    Color c = new Color(hue, sat, light, alpha);
} catch (RuntimeException e) {
    if (e.getMessage().startsWith("Invalid hue")) {
        c = new Color(Math.floorMod(hue, 360), sat, light, alpha);
    } else throw e;
}

When it happens

Trigger: An extension (or Dev UI code) constructs a Color (e.g. via its factory/fromHSL path) with a negative hue or hue greater than 360 during build-time content generation.

Common situations: A custom extension computing a theme hue from a hash or config value without normalizing modulo 360; off-by-one on a 360-based calculation; hand-edited extension color values.

Related errors

• Invalid saturation, number needs to be between 0 and 100. 0%
• Invalid lightness, 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/d581cf3ecd64d866. Report an issue: GitHub.