microg/GmsCore · error · IllegalArgumentException

Non-negative loitering delay needs to be set when transition

Error message

Non-negative loitering delay needs to be set when transition types include GEOFENCE_TRANSITION_DWELLING.

What it means

When transition types include GEOFENCE_TRANSITION_DWELL, the builder requires a non-negative loitering delay, since dwell detection is defined by how long the user stays inside. If setLoiteringDelay was never called (default -1) or was set negative, build() throws this IllegalArgumentException.

Source

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

        private float radius;
        private long expirationTime = Long.MIN_VALUE;
        private int loiteringDelay = -1;
        private int notificationResponsiveness;
        private String requestId;
        private @TransitionTypes int transitionTypes;

        /**
         * Creates a geofence object.
         *
         * @throws IllegalArgumentException if any parameters are not set or out of range
         */
        public Geofence build() throws IllegalArgumentException {
            if (requestId == null) {
                throw new IllegalArgumentException("Request ID not set.");
            } else if (transitionTypes == 0) {
                throw new IllegalArgumentException("Transition types not set.");
            } else if ((transitionTypes & GEOFENCE_TRANSITION_DWELL) > 0 && loiteringDelay < 0) {
                throw new IllegalArgumentException("Non-negative loitering delay needs to be set when transition types include GEOFENCE_TRANSITION_DWELLING.");
            } else if (expirationTime == Long.MIN_VALUE) {
                throw new IllegalArgumentException("Expiration not set.");
            } else if (regionType == -1) {
                throw new IllegalArgumentException("Geofence region not set.");
            } else if (notificationResponsiveness < 0) {
                throw new IllegalArgumentException("Notification responsiveness should be nonnegative.");
            } else {
                return new ParcelableGeofence(requestId, expirationTime, regionType, latitude, longitude, radius, transitionTypes, notificationResponsiveness, loiteringDelay);
            }
        }

        /**
         * Sets the region of this geofence. The geofence represents a circular area on a flat, horizontal plane.
         *
         * @param latitude  latitude in degrees, between -90 and +90 inclusive
         * @param longitude longitude in degrees, between -180 and +180 inclusive
         * @param radius    radius in meters
         */

View on GitHub (pinned to 157c9d86ac)

Solutions

Call setLoiteringDelay(delayMillis) with a positive value (e.g. 30000 for 30s) before build()
Or remove GEOFENCE_TRANSITION_DWELL from setTransitionTypes() if dwell events are not needed

Example fix

// before
builder.setTransitionTypes(Geofence.GEOFENCE_TRANSITION_DWELL);
Geofence fence = builder.build(); // throws
// after
builder.setTransitionTypes(Geofence.GEOFENCE_TRANSITION_DWELL)
       .setLoiteringDelay(30000);
Geofence fence = builder.build();

Defensive patterns

Strategy: validation

Validate before calling

if ((transitionTypes & Geofence.GEOFENCE_TRANSITION_DWELL) != 0 && loiteringDelayMillis <= 0) {
    throw new IllegalStateException("DWELL transitions require setLoiteringDelay() > 0");
}

Type guard

static boolean dwellNeedsDelay(int transitionTypes, long loiteringDelay) { return (transitionTypes & Geofence.GEOFENCE_TRANSITION_DWELL) != 0 && loiteringDelay >= 0; }

Try / catch

try { return builder.build(); } catch (IllegalArgumentException e) { if (e.getMessage().contains("loitering")) { builder.setLoiteringDelay(30000); return builder.build(); } throw e; }

Prevention

Whenever adding GEOFENCE_TRANSITION_DWELL, immediately add setLoiteringDelay() on the same line/chain
Pick a sensible default dwell delay (e.g. 30s) in your geofence factory

When it happens

Trigger: Calling build() after setTransitionTypes() included GEOFENCE_TRANSITION_DWELL but without calling setLoiteringDelay() with a value >= 0 (default loiteringDelay is -1).

Common situations: Adding DWELL to transition types later without adding the loitering delay; assuming a default dwell delay exists; migrating code from enter/exit-only fences to dwell fences.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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