microg/GmsCore · error · IllegalArgumentException

Transparency must be in the range [0..1]

Error message

Transparency must be in the range [0..1]

What it means

TileOverlayOptions.transparency(float) validates that the given transparency value lies in the closed range [0..1], where 0 is fully opaque and 1 fully transparent. Any value outside this range (negative or greater than 1) throws IllegalArgumentException immediately, before the options object is mutated. This is a fail-fast argument validation guard in the microG play-services-maps replacement library.

Source

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

        this.tileProvider = tileProvider;
        this.tileProviderBinder = new ITileProviderDelegate.Stub() {
            @Override
            public Tile getTile(int x, int y, int zoom) throws RemoteException {
                return tileProvider.getTile(x, y, zoom);
            }
        };
        return this;
    }

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

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

    /**
     * Specifies the tile overlay's zIndex, i.e., the order in which it will be drawn where
     * overlays with larger values are drawn above those with lower values. See the documentation
     * at the top of this class for more information about zIndex.

View on GitHub (pinned to 157c9d86ac)

Solutions

1. Clamp the value into [0..1] before calling transparency(), e.g. Math.max(0f, Math.min(1f, v)).
2. If the source value is a percentage (0-100), divide by 100 before passing it.
3. If the source is an alpha 0-255, divide by 255f before passing it.
4. Validate user/config-supplied values at the boundary and reject or clamp with a clear log instead of propagating raw input.

Example fix

// before
float t = getUserTransparencyPercent(); // e.g. 80
TileOverlayOptions o = new TileOverlayOptions().transparency(t); // throws
// after
float t = getUserTransparencyPercent() / 100f;
TileOverlayOptions o = new TileOverlayOptions().transparency(Math.max(0f, Math.min(1f, t)));

public static boolean isValidTransparency(float t) {
    return t >= 0.0f && t <= 1.0f;
}
// call site
float t = rawValue / 100f; // if percentage
if (!isValidTransparency(t)) t = Math.max(0f, Math.min(1f, t));
options.transparency(t);

public static Float safeTransparency(Float t) {
    if (t == null) return null;
    return Math.max(0f, Math.min(1f, t));
}

try {
    options.transparency(t);
} catch (IllegalArgumentException e) {
    Log.w(TAG, "transparency out of range, clamping", e);
    options.transparency(Math.max(0f, Math.min(1f, t)));
}

When it happens

Trigger: Calling new TileOverlayOptions().transparency(x) with x < 0.0f or x > 1.0f, e.g. transparency(1.5f), transparency(-0.1f), or a computed ratio expressed as a percentage (e.g. transparency(50)) instead of a fraction.

Common situations: Developers passing percentages instead of fractions, dividing in the wrong order (total/part instead of part/total), loading the value from unvalidated user input or remote config, or off-by-one scaling from 0-255 alpha values.

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

• deleteAll was set to true but keys were also provided
• Element in keys cannot be null or empty
• retrieveAll was set to true but other constraint(s) was also
• Element in keys cannot be null or empty
• Required account information missing

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