microg/GmsCore · error · IllegalArgumentException

throttle behavior {throttleBehavior} must be a ThrottleBehav

Error message

throttle behavior {throttleBehavior} must be a ThrottleBehavior.THROTTLE_* constant

What it means

ThrottleBehaviorUtil.checkValidThrottleBehavior validates that the given int is one of the ThrottleBehavior.THROTTLE_* constants (isValidThrottleBehavior). Any other integer throws IllegalArgumentException, because throttle behavior must be a well-defined enum value for the location request.

Source

Thrown at play-services-location/src/main/java/org/microg/gms/location/ThrottleBehaviorUtil.java:25

import androidx.annotation.NonNull;
import com.google.android.gms.location.ThrottleBehavior;

public class ThrottleBehaviorUtil {
    public static boolean isValidThrottleBehavior(@ThrottleBehavior int throttleBehavior) {
        switch (throttleBehavior) {
            default:
                return false;
            case ThrottleBehavior.THROTTLE_BACKGROUND:
            case ThrottleBehavior.THROTTLE_ALWAYS:
            case ThrottleBehavior.THROTTLE_NEVER:
                return true;
        }
    }

    public static int checkValidThrottleBehavior(@ThrottleBehavior int throttleBehavior) {
        if (!isValidThrottleBehavior(throttleBehavior)) {
            throw new IllegalArgumentException("throttle behavior " + throttleBehavior + " must be a ThrottleBehavior.THROTTLE_* constant");
        }
        return throttleBehavior;
    }

    @NonNull
    public static String throttleBehaviorToString(@ThrottleBehavior int throttleBehavior) {
        switch (throttleBehavior) {
            case ThrottleBehavior.THROTTLE_BACKGROUND:
                return "THROTTLE_BACKGROUND";
            case ThrottleBehavior.THROTTLE_ALWAYS:
                return "THROTTLE_ALWAYS";
            case ThrottleBehavior.THROTTLE_NEVER:
                return "THROTTLE_NEVER";
            default:
                throw new IllegalArgumentException();
        }
    }
}

View on GitHub (pinned to 157c9d86ac)

Solutions

1. Use only the defined ThrottleBehavior.THROTTLE_* constants
2. Never bitwise-combine throttle behavior constants
3. Validate externally supplied ints with isValidThrottleBehavior before use

Example fix

// before
int behavior = 0; // not a THROTTLE_* constant
checkValidThrottleBehavior(behavior);
// after
int behavior = ThrottleBehavior.THROTTLE_ALWAYS_ON;
checkValidThrottleBehavior(behavior);

// whitelist ThrottleBehavior.THROTTLE_* constants before calling
if (behavior != ThrottleBehavior.THROTTLE_ALWAYS_ON
    && behavior != ThrottleBehavior.THROTTLE_BACKGROUND_RESTRICTED
    && behavior != ThrottleBehavior.THROTTLE_NEVER) {
    behavior = ThrottleBehavior.THROTTLE_ALWAYS_ON;
}

try { ThrottleBehaviorUtil.checkValidThrottleBehavior(b); } catch (IllegalArgumentException e) { b = ThrottleBehavior.THROTTLE_ALWAYS_ON; }

When it happens

Trigger: Passing an arbitrary int (0, 3, combined bitfield, or a constant from another enum) where a ThrottleBehavior value is expected, e.g. in LocationRequest building code that validates via checkValidThrottleBehavior.

Common situations: Config/remote-config supplied throttle values not whitelisted; confusing Priority or Granularity constants with ThrottleBehavior; hard-coded numbers instead of ThrottleBehavior.THROTTLE_* references.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• granularity {granularity} must be a Granularity.GRANULARITY_
• priority {priority} must be a Priority.PRIORITY_* constant
• invalid radius:
• invalid latitude:
• invalid longitude:

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