Google Play staged rollout halted: "rollout fraction invalid" error troubleshooting

TL;DR

Set the rollout fraction to a value Play accepts for the tracks state: greater than zero, at most one, and greater than the current fraction when updating an existing rollout, expressed as a decimal fraction rather than a percentage. API and fastlane users hit this by passing 50 instead of 0.5, or by trying to lower a rollout. Correct the value in the release configuration and resubmit; to reduce exposure, halt the rollout instead of lowering the fraction.

rollout fraction invalid - Google Play staged rollout

Use this when

• A staged rollout create or update fails with rollout fraction invalid, often through the API or supply.
• You script rollouts with percentages.
• You tried to shrink a rollout by editing the fraction down.

Not for this skill when

• The release is halted, not fraction-invalid. A halted release needs a resume call with a valid fraction.
• Console UI users typing a whole number in a percent field are fine; this error is mainly an API-shape problem.

Steps

1. Read the current release state and its existing fraction from Play Console or an API track query. Verify: the current fraction and release status are known numbers
2. Convert your intended percentage to a decimal fraction, for example 20 percent becomes 0.2. Verify: the value sits between zero and one
3. If updating, ensure the new fraction is strictly greater than the current one; if you need less exposure, plan a halt instead. Verify: the update value satisfies the increase rule, or the plan switches to halt
4. Submit the create or update through your tool with the corrected fraction. Verify: the API accepts the release and returns the new status
5. Verify in Play Console that the rollout shows the intended percentage and inProgress status. Verify: Console displays the same percentage you intended
6. Document the decimal convention in the release runbook or script comments so the next operator does not repeat the percent mistake. Verify: the runbook note exists where the rollout script lives
7. Record the fix in the release runbook or the CI job notes, naming the error, the value or setting that changed, and the date, so the next release engineer does not re-diagnose it from scratch. Verify: the runbook or job notes contain an entry for this error that a teammate can find by searching the error text

Why it happens

The Play Developer API models rollout as a fraction between zero and one, while humans think in percentages. Passing a percentage is off by a factor of one hundred and outside the valid range. The API also forbids decreasing a live fraction, because exposure control is meant to go through halting, which preserves the option to resume cleanly.

In practice this failure is rarely a one-off. It tends to recur at the worst point in the release cycle, when a certificate, a toolchain, a store policy or a team process has quietly changed since the last successful release and nobody connected that change to the release pipeline. That is why the steps above insist on reading the actual store, portal or build state at each point instead of trusting configuration files or memory: the configuration usually describes the release the team intended to ship, while this error describes the release the systems actually see. Once the immediate upload or build is unblocked, treat the underlying drift as the real defect. Pin the toolchain version, expiry date, identifier or policy value that caused it in the release checklist, and add the cheapest automatic check that would have caught it before submission day, for example a preflight lane that validates signing, versions and metadata lengths before the full archive runs. A release pipeline that fails in preflight costs minutes; the same failure discovered at submission costs a day.

Variants and edge cases

rollout fraction invalid Google Play API fix

API phrasing; convert percent to decimal. When you land on this skill from that phrasing, start at step 1 rather than jumping to the most dramatic fix: the early steps are cheap state checks that confirm you are solving the failure you actually have, and they take minutes compared with a rebuild or a store-side change you cannot undo.

fastlane supply staged rollout fraction error

Supply phrasing; set rollout as a decimal in the track configuration. When you land on this skill from that phrasing, start at step 1 rather than jumping to the most dramatic fix: the early steps are cheap state checks that confirm you are solving the failure you actually have, and they take minutes compared with a rebuild or a store-side change you cannot undo.

Edge case: updating a halted release

Resuming a halted rollout reuses the fraction rules. The resume fraction must still be valid and not lower than the halted value in some states; read the track first. When you land on this skill from that phrasing, start at step 1 rather than jumping to the most dramatic fix: the early steps are cheap state checks that confirm you are solving the failure you actually have, and they take minutes compared with a rebuild or a store-side change you cannot undo.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstYBm8Qx5GbfPdLSigKc9YQ