microg/GmsCore · error · IllegalArgumentException

height must not be negative

Error message

height must not be negative

What it means

GroundOverlayOptions.position(LatLng, float width, float height) throws IllegalArgumentException when the height argument is negative. The overlay is sized explicitly from width and height in meters, so negative dimensions have no geometric meaning. Note this overload first delegates to position(location, width), so width and null-location checks run before the height check.

Source

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

     * dimensions specified (i.e., its proportions will not necessarily be preserved).
     *
     * @param location the location on the map {@code LatLng} to which the anchor point in the
     *                 given image will remain fixed. The anchor will remain fixed to the position
     *                 on the ground when transformations are applied (e.g., setDimensions,
     *                 setBearing, etc.).
     * @param width    the width of the overlay (in meters)
     * @param height   the height of the overlay (in meters)
     * @return this {@link GroundOverlayOptions} object with a new position set.
     * @throws IllegalArgumentException if anchor is null
     * @throws IllegalArgumentException if width or height are negative
     * @throws IllegalStateException    if the position was already set using
     *                                  {@link #positionFromBounds(LatLngBounds)}
     */
    public GroundOverlayOptions position(LatLng location, float width, float height)
            throws IllegalArgumentException, IllegalStateException {
        position(location, width);
        if (height < 0)
            throw new IllegalArgumentException("height must not be negative");
        this.height = height;
        return this;
    }

    /**
     * Specifies the position for this ground overlay using an anchor point (a {@link LatLng}) and
     * the width (in meters). When rendered, the image will retain its proportions from the bitmap,
     * i.e., the height will be calculated to preserve the original proportions of the image.
     *
     * @param location the location on the map {@link LatLng} to which the anchor point in the
     *                 given image will remain fixed. The anchor will remain fixed to the position
     *                 on the ground when transformations are applied (e.g., setDimensions,
     *                 setBearing, etc.).
     * @param width    the width of the overlay (in meters). The height will be determined
     *                 automatically based on the image proportions.
     * @return this {@link GroundOverlayOptions} object with a new position set.
     * @throws IllegalArgumentException if anchor is null
     * @throws IllegalArgumentException if width is negative

View on GitHub (pinned to 157c9d86ac)

Solutions

1. Validate/clamp height to a non-negative value before calling position(): if (height < 0) height = 0; or fix the computation.
2. Verify the arguments are in the right order — position(LatLng, width, height) — and that the size calculation cannot go negative.
3. If only width matters, use the two-argument overload position(LatLng, float) so height is derived from the image.

Example fix

// before
float height = imgHeightMeters * scale; // scale may be negative
map.addGroundOverlay(options.position(center, width, height));

// after
float height = Math.max(0f, imgHeightMeters * scale);
map.addGroundOverlay(options.position(center, width, height));

if (height < 0f) throw new IllegalArgumentException("caller bug: negative height " + height); // or clamp

boolean validSize(float w, float h) { return w >= 0f && h >= 0f; }

try {
    options.position(center, width, height);
} catch (IllegalArgumentException e) {
    options.position(center, width, Math.max(0f, height));
}

When it happens

Trigger: Calling groundOverlayOptions.position(latLng, width, height) with height < 0, typically from a computed dimension (e.g. scaling an image's meter size by a negative factor) or swapped/mistyped arguments.

Common situations: Deriving overlay size from image aspect ratio and a scale factor that can be negative after a sign error; unit-conversion mistakes (feet vs meters is fine, but a negated delta is not); copy-paste where width and height variables are swapped in a call.

Related errors

• width must not be negative
• transparency must be in range [0..1]
• 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/edff5c0d75815aac. Report an issue: GitHub.