microg/GmsCore · error · IllegalArgumentException

location must not be null

Error message

location must not be null

What it means

GroundOverlayOptions.position(LatLng, float width) throws IllegalArgumentException when the location argument is null. A ground overlay must be anchored at a real LatLng, so the library rejects a null anchor eagerly. This is the shared position path also used by the three-argument overload, so it is checked first there.

Source

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

     * 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
     * @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)}

View on GitHub (pinned to 157c9d86ac)

Solutions

1. Null-check the LatLng before calling position() and skip adding the overlay or fall back to a known default location.
2. Handle null geocoding/results upstream and resolve to a concrete coordinate before configuring the overlay.
3. Guard bundle restoration: if (bundle.containsKey(KEY)) { LatLng loc = bundle.getParcelable(KEY); if (loc != null) ... }

Example fix

// before
LatLng center = geocode(address); // may be null
map.addGroundOverlay(new GroundOverlayOptions().position(center, 1000f));

// after
LatLng center = geocode(address);
if (center != null) {
    map.addGroundOverlay(new GroundOverlayOptions().position(center, 1000f));
}

if (location == null) { return; /* skip overlay or use default */ }

boolean canPlaceOverlay(LatLng loc) { return loc != null; }

try {
    options.position(location, width);
} catch (IllegalArgumentException e) {
    // resolve location or skip overlay creation
}

When it happens

Trigger: Calling position(null, width) (or the width+height overload with a null LatLng), or passing a nullable LatLng resolved from geocoding, a saved bundle, or a marker lookup that returned null.

Common situations: Geocoder or places-API result is null (no match for the address string); restoring overlay state from a Bundle where the LatLng key is missing; computing a position from a Nullable location before the first fix.

Related errors

• null camera target
• height must not be negative
• width must not be negative
• Position already set using positionFromBounds()
• Position already set using position()

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