microg/GmsCore · error · IllegalArgumentException

transparency must be in range [0..1]

Error message

transparency must be in range [0..1]

What it means

GroundOverlayOptions.transparency(float) throws IllegalArgumentException when the transparency value is outside the range [0..1]. Transparency is a normalized float: 0 is fully opaque (the default) and 1 is fully invisible. Values such as percentages (0-100) or signed/clamped-escaped floats are rejected.

Source

Thrown at play-services-maps/src/main/java/com/google/android/gms/maps/model/GroundOverlayOptions.java:327

        if (location != null)
            throw new IllegalStateException("Position already set using position()");
        this.bounds = bounds;
        return this;
    }

    /**
     * Specifies the transparency of the ground overlay. The default transparency is {code 0}
     * (opaque).
     *
     * @param transparency a float in the range {@code [0..1]} where {@code 0} means that the
     *                     ground overlay is opaque and {code 1} means that the ground overlay is
     *                     transparent
     * @return this {@link GroundOverlayOptions} object with a new visibility setting.
     * @throws IllegalArgumentException if the transparency is outside the range [0..1].
     */
    public GroundOverlayOptions transparency(float transparency) throws IllegalArgumentException {
        if (transparency < 0 || transparency > 1)
            throw new IllegalArgumentException("transparency must be in range [0..1]");
        this.transparency = transparency;
        return this;
    }

    /**
     * Specifies the visibility for the ground overlay. The default visibility is {@code true}.
     *
     * @return this {@link GroundOverlayOptions} object with a new visibility setting.
     */
    public GroundOverlayOptions visible(boolean visible) {
        this.visible = visible;
        return this;
    }

    /**
     * Specifies the ground overlay's zIndex, i.e., the order in which it will be drawn. See the
     * documentation at the top of this class for more information about zIndex.
     *

View on GitHub (pinned to 157c9d86ac)

Solutions

1. Convert percentages: if the value is 0-100, divide by 100 before calling transparency().
2. Clamp into range: transparency = Math.max(0f, Math.min(1f, value));
3. Remember the semantic is transparency, not opacity — invert if your source value is opacity (1 - opacity).

Example fix

// before
float pct = 75; // percent opaque
options.transparency(pct); // throws

// after
float opacity = 75f / 100f;
options.transparency(1f - opacity); // 0.25 transparency, clamped to [0..1]

if (t < 0f || t > 1f) t = Math.max(0f, Math.min(1f, t));

float clampTransparency(float t) { return Math.max(0f, Math.min(1f, t)); }

try {
    options.transparency(value);
} catch (IllegalArgumentException e) {
    options.transparency(clampTransparency(value));
}

When it happens

Trigger: Calling transparency(50) (percentage instead of fraction), transparency(-0.1f), transparency(1.5f), or passing a computed/interpolated value that drifts outside [0..1].

Common situations: Confusing percentage-based opacity (0-100) with the library's 0-1 convention; animating transparency with an easing function that overshoots; storing transparency in config with inconsistent scaling.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• height must not be negative
• width must not be negative
• Tilt needs to be between 0 and 90 inclusive
• location must not be null
• Position already set using positionFromBounds()

AI-assisted analysis of microg/GmsCore@157c9d86ac (2026-09-06). Data as JSON: /api/errors/297215f45f8e348a. Report an issue: GitHub.