{"record":{"id":"e0b3472bbfd3ca9b","repo":"microg/GmsCore","slug":"transparency-must-be-in-the-range-0-1","errorCode":null,"errorMessage":"Transparency must be in the range [0..1]","messagePattern":"Transparency must be in the range \\[0\\.\\.1\\]","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"play-services-maps/src/main/java/com/google/android/gms/maps/model/TileOverlayOptions.java","lineNumber":142,"sourceCode":"        this.tileProvider = tileProvider;\n        this.tileProviderBinder = new ITileProviderDelegate.Stub() {\n            @Override\n            public Tile getTile(int x, int y, int zoom) throws RemoteException {\n                return tileProvider.getTile(x, y, zoom);\n            }\n        };\n        return this;\n    }\n\n    /**\n     * Specifies the transparency of the tile overlay. The default transparency is {@code 0} (opaque).\n     *\n     * @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.\n     * @return this {@link TileOverlayOptions} object with a new transparency setting.\n     * @throws IllegalArgumentException if the transparency is outside the range [0..1].\n     */\n    public TileOverlayOptions transparency(float transparency) {\n        if (transparency < 0.0f || transparency > 1.0f) throw new IllegalArgumentException(\"Transparency must be in the range [0..1]\");\n        this.transparency = transparency;\n        return this;\n    }\n\n    /**\n     * Specifies the visibility for the tile overlay. The default visibility is {@code true}.\n     *\n     * @return this {@link TileOverlayOptions} object with a new visibility setting.\n     */\n    public TileOverlayOptions visible(boolean visible) {\n        this.visible = visible;\n        return this;\n    }\n\n    /**\n     * Specifies the tile overlay's zIndex, i.e., the order in which it will be drawn where\n     * overlays with larger values are drawn above those with lower values. See the documentation\n     * at the top of this class for more information about zIndex.","sourceCodeStart":124,"sourceCodeEnd":160,"githubUrl":"https://github.com/microg/GmsCore/blob/157c9d86ac46c195a86c2f15ab55c84036223f95/play-services-maps/src/main/java/com/google/android/gms/maps/model/TileOverlayOptions.java#L124-L160","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Clamp the value into [0..1] before calling transparency(), e.g. Math.max(0f, Math.min(1f, v)).","If the source value is a percentage (0-100), divide by 100 before passing it.","If the source is an alpha 0-255, divide by 255f before passing it.","Validate user/config-supplied values at the boundary and reject or clamp with a clear log instead of propagating raw input."],"exampleFix":"// before\nfloat t = getUserTransparencyPercent(); // e.g. 80\nTileOverlayOptions o = new TileOverlayOptions().transparency(t); // throws\n// after\nfloat t = getUserTransparencyPercent() / 100f;\nTileOverlayOptions o = new TileOverlayOptions().transparency(Math.max(0f, Math.min(1f, t)));","handlingStrategy":"validation","validationCode":"public static boolean isValidTransparency(float t) {\n    return t >= 0.0f && t <= 1.0f;\n}\n// call site\nfloat t = rawValue / 100f; // if percentage\nif (!isValidTransparency(t)) t = Math.max(0f, Math.min(1f, t));\noptions.transparency(t);","typeGuard":"public static Float safeTransparency(Float t) {\n    if (t == null) return null;\n    return Math.max(0f, Math.min(1f, t));\n}","tryCatchPattern":"try {\n    options.transparency(t);\n} catch (IllegalArgumentException e) {\n    Log.w(TAG, \"transparency out of range, clamping\", e);\n    options.transparency(Math.max(0f, Math.min(1f, t)));\n}","preventionTips":["Always normalize percentages (divide by 100) and 0-255 alphas (divide by 255) before calling transparency().","Clamp any computed or user-supplied value into [0..1] at a single utility method.","Add a unit test asserting the clamping helper never emits values outside [0..1].","Validate remote-config/user values at ingestion time, not at API call time."],"tags":["android","maps","argument-validation","illegal-argument"],"backgroundTag":"value-out-of-range","analyzedSha":"157c9d86ac46c195a86c2f15ab55c84036223f95","analyzedAt":"2026-09-06T17:27:33.892Z","contentChangedAt":"2026-09-06T17:27:33.892Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}