'The field apiVersion can't be' on a Salesforce deploy

What does this API version error mean?

Every flow, Apex class, trigger and Lightning component carries an API version in its file. The target org refuses anything newer than the release it runs. Salesforce Help puts the usual situation like this: the component was built in a source org, often a preview sandbox, that runs a newer release than the destination (Salesforce Help, 26-01-2026).

There are two wordings. Against an org on API version 68.0, a flow with apiVersion 69.0 or 99.0 returned:

The field apiVersion can't be "99". Enter a different value and try again.

An Apex class with the same problem returned a shorter line:

Invalid api version:99.0

Both appeared for 69.0 as well, one step above what that org supported.

What causes it?

• You built the component in a preview or pre-release sandbox, and its default API version is one ahead of production.
• A script or template wrote a high version into the meta-xml files, or someone copied files from a project on a newer release.
• The sourceApiVersion in sfdx-project.json is higher than the target supports, so retrieved files carry the new number.

How do I fix it in Setup?

Salesforce Help gives two options. Wait until both orgs are on the same release, or lower the component's API version by one from the number in the error and upload again (Salesforce Help).

1. Read the version in the message, for example 69.
2. In the source org, open the flow and save a new version, or open the Apex class and edit its version in the Version Settings tab of the class.
3. Choose a version the target supports. The CLI output below shows what the target supports.
4. Create a new change set, since an uploaded one cannot be edited, and upload it.
5. Validate, then deploy.

How do I fix it with the CLI?

First find what the target runs:

sf org display -o target-org

Look for the API Version line. Then fix the file. For an Apex class it is the meta-xml next to it:

<apiVersion>68.0</apiVersion>

For a flow, it is the apiVersion element in the .flow-meta.xml file. Lower sourceApiVersion in sfdx-project.json to the same number if it is too high, then validate:

sf project deploy start --dry-run --source-dir force-app --test-level NoTestRun -o target-org

How do I prevent it?

Build in a sandbox on the same release as production, or expect to lower versions by hand when you build in a preview sandbox. Put the API version on your code review checklist, next to the code. The same cause shows up in change sets, covered in the change set errors guide. Flows are covered on flow deploy errors, and AI Salesforce deployments covers the rest of the release path.

The Spring '27 release deployment checklist covers the API version change for the next release.