microg/GmsCore · error · IllegalArgumentException

minUpdateDistanceMeters must be greater than or equal to 0

Error message

minUpdateDistanceMeters must be greater than or equal to 0

What it means

LocationRequest.Builder.setMinUpdateDistanceMeters() requires a non-negative distance in meters; negative values are invalid. The library throws this IllegalArgumentException when the argument is negative, because a negative minimum update distance has no physical meaning.

Source

Thrown at play-services-location/src/main/java/com/google/android/gms/location/LocationRequest.java:778

         * The default value is {@link Integer#MAX_VALUE}.
         */
        @NonNull
        public Builder setMaxUpdates(int maxUpdates) {
            if (maxUpdates <= 0) throw new IllegalArgumentException("maxUpdates must be greater than 0");
            this.maxUpdates = maxUpdates;
            return this;
        }

        /**
         * Sets the minimum distance required between consecutive location updates. If a derived location update is not at least
         * the specified distance away from the previous location update delivered to the client, it will not be delivered. This may
         * also allow additional power savings under some circumstances.
         * <p>
         * The default value is 0.
         */
        @NonNull
        public Builder setMinUpdateDistanceMeters(float minUpdateDistanceMeters) {
            if (minUpdateDistanceMeters < 0) throw new IllegalArgumentException("minUpdateDistanceMeters must be greater than or equal to 0");
            this.minUpdateDistanceMeters = minUpdateDistanceMeters;
            return this;
        }

        /**
         * Sets the fastest allowed interval of location updates. Location updates may arrive faster than the desired interval
         * ({@link #setIntervalMillis(long)}), but will never arrive faster than specified here.
         * <p>
         * This may be set to the special value {@link #IMPLICIT_MIN_UPDATE_INTERVAL} in which case the minimum update interval will
         * be the same as the interval. {@link FusedLocationProviderClient} APIs make some allowance for jitter with the minimum
         * update interval, so clients need not worry about location updates that arrive a couple milliseconds too early being
         * rejected.
         * <p>
         * The default value is {@link #IMPLICIT_MIN_UPDATE_INTERVAL}.
         */
        @NonNull
        public Builder setMinUpdateIntervalMillis(long minUpdateIntervalMillis) {
            if (minUpdateIntervalMillis < 0 && minUpdateIntervalMillis != IMPLICIT_MIN_UPDATE_INTERVAL)

View on GitHub (pinned to 157c9d86ac)

Solutions

Pass a non-negative float (0 disables the distance constraint).
Clamp with Math.max(0, distance) before building.
Verify the sign of the computed distance.
Omit the call if you want the default of 0.

Example fix

// before
builder.setMinUpdateDistanceMeters(-10f);
// after
builder.setMinUpdateDistanceMeters(Math.max(0f, minDistanceMeters));

Defensive patterns

Strategy: validation

Validate before calling

if (minUpdateDistanceMeters < 0) { throw new IllegalArgumentException("distance must be >= 0"); }
builder.setMinUpdateDistanceMeters(minUpdateDistanceMeters);

Try / catch

try {
    builder.setMinUpdateDistanceMeters(distance);
} catch (IllegalArgumentException e) {
    builder.setMinUpdateDistanceMeters(0f);
}

Prevention

Clamp computed distances with Math.max(0f, value)
Check the sign of variables reused as distances
Omit the setter to accept the default of 0

When it happens

Trigger: Calling setMinUpdateDistanceMeters(float) with any value < 0, e.g. a sign error or a computed delta that went negative.

Common situations: Subtracting distances in the wrong order, reusing a signed offset variable as a distance, or parsing user input without checking sign.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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