microg/GmsCore · error · IllegalArgumentException

width must not be negative

Error message

width must not be negative

What it means

GroundOverlayOptions.position(LatLng, float width) throws IllegalArgumentException when the width argument is negative. Width (in meters) defines the overlay's ground footprint; a negative value is meaningless and rejected. This check runs after the null-location check and before the positionFromBounds conflict check.

Source

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

     *
     * @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
     * @throws IllegalStateException    if the position was already set using
     *                                  {@link #positionFromBounds(LatLngBounds)}
     */
    public GroundOverlayOptions position(LatLng location, float width)
            throws IllegalArgumentException, IllegalStateException {
        if (location == null)
            throw new IllegalArgumentException("location must not be null");
        if (width < 0)
            throw new IllegalArgumentException("width must not be negative");
        if (bounds != null)
            throw new IllegalStateException("Position already set using positionFromBounds()");
        this.location = location;
        this.width = width;
        return this;
    }

    /**
     * Specifies the position for this ground overlay. When rendered, the image will be scaled to
     * fit the bounds (i.e., its proportions will not necessarily be preserved).
     *
     * @param bounds a {@link LatLngBounds} in which to place the ground overlay
     * @return this {@link GroundOverlayOptions} object with a new position set.
     * @throws IllegalStateException if the position was already set using
     *                               {@link #position(LatLng, float)} or
     *                               {@link #position(LatLng, float, float)}
     */
    public GroundOverlayOptions positionFromBounds(LatLngBounds bounds)

View on GitHub (pinned to 157c9d86ac)

Solutions

1. Clamp width before the call: width = Math.max(0f, computedWidth);
2. Fix the size computation so it cannot produce negative values, or validate configuration inputs at load time.
3. Consider positionFromBounds(LatLngBounds) if the overlay should derive its size from geography instead of an explicit width.

Example fix

// before
float width = baseWidth * zoomScale; // may be negative
options.position(center, width);

// after
float width = Math.max(0f, baseWidth * zoomScale);
options.position(center, width);

if (width < 0f) width = 0f; // or fix the computation

boolean validWidth(float w) { return w >= 0f; }

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

When it happens

Trigger: Calling position(latLng, width) with width < 0, e.g. a computed meter width from a scale factor that went negative, an argument-order mix-up, or an unvalidated user-entered size.

Common situations: Overlay sizes derived from zoom-dependent scaling calculations that can invert sign; mistakes converting between units; feeding untrusted configuration values directly into the options builder.

Related errors

• height 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/564549bbd8ebb297. Report an issue: GitHub.