REQUIRED_FIELD_MISSING when deactivating a Flow via the Tooling API

The error names a missing required field, so you go looking for the field you forgot. There isn't one. The body is simply the wrong shape, and the platform reports it in the least helpful way available.

Salesforce · Flow · Tooling API · data migration

The fix, first

PATCH the FlowDefinition record and wrap your change in a Metadata object. Setting activeVersionNumber to 0 is what deactivates the flow:

A successful call returns HTTP 204 No Content. To reactivate, send the same request with the version number that was previously live:

Why the error is worded so badly

The common failing attempt looks reasonable:

The intuition is fair — FlowDefinition exposes an active version, so you point at the version record you want. But ActiveVersion is not a writable field on FlowDefinition. The only writable surface is the Metadata compound field, which is where the Tooling API keeps the mutable definition of the record.

Because your body contains nothing the platform recognises as writable, validation runs as though you sent an empty update — and the field it wanted, Metadata, is reported as missing. The error is technically accurate and practically misleading. You didn't forget a field; you sent fields that don't exist.

The DurableId trap

The second failure mode is subtler and produces NOT_FOUND rather than REQUIRED_FIELD_MISSING, usually right after you've fixed the body.

Most people list flows using FlowDefinitionView — it's a friendly read-only REST object with the label, API name, active version, and process type all in one place. It's the right thing to read from. It is not the thing you write to, and its Id is not the Id the Tooling API wants.

So the mapping is FlowDefinitionView.DurableId → FlowDefinition.Id. Pass FlowDefinitionView.Id into the PATCH URL and you will get a not-found response for a flow you are looking straight at.

Process Builder is the same mechanism

Process Builder processes are flows underneath, distinguished by ProcessType = 'Workflow'. They activate and deactivate through the identical FlowDefinition PATCH with the identical body. If you are switching automations off before a data load, you can handle flows and processes in one pass — just report them separately, because admins think of them as different things and will want to see them listed that way.

Why version 44 keeps coming up

Older material on this topic describes deploying a .flowDefinition-meta.xml file with <activeVersionNumber>0</activeVersionNumber> through the Metadata API. That is still valid and is the deployment-based route. The Tooling API PATCH described here is the runtime equivalent — no package, no deploy, no test run — which is what you want when you're disabling forty flows for a load window and re-enabling them two hours later.

Both routes converge on the same concept: activeVersionNumber = 0 means inactive. If you have seen conflicting advice about a status field or an IsActive flag, that is why — the flow itself has no writable status; the definition's active version number carries the state.

Frequently asked