Salesforce Dictionary - Free Salesforce GlossarySalesforce Dictionary
All errors
CLI · sf

The resource ... is not allowed by API version <X>

Your sf CLI (or the metadata API call) is using an API version older or newer than what the requested resource supports. Either upgrade the CLI, change the project's `sourceApiVersion`, or use a feature available in the version you're on.

Also seen asresource not allowed by version·API version mismatch·Resource not allowed·INVALID_VERSION

Salesforce versions its API; each release adds new resources and fields. If your CLI sends a request against a resource that exists only in API version 60.0 but the request says version 50.0, the platform rejects it.

The two version places

Two configurations interact:

1. The CLI's bundled API version

The sf CLI ships with a default API version. Each sf major release bumps it. To see yours:

sf --version

Or check ~/.sf/config.json for an explicit override.

2. Your project's sourceApiVersion

In sfdx-project.json at the root of your repo:

{
  "packageDirectories": [{ "path": "force-app", "default": true }],
  "sourceApiVersion": "60.0"
}

This tells the CLI which API version to send against the org. It's how you keep multiple repositories deploying against the same org without forcing all of them to upgrade in lockstep.

When versions clash

Three usual symptoms:

Symptom 1: a new metadata type is unknown

sf project deploy start --metadata RecommendationStrategy:MyStrategy
# Error: The resource RecommendationStrategy is not allowed by API version 50.0

Recommendation Strategies were added in API version 56.0. If your project's sourceApiVersion is 50.0, the deploy fails. Fix: bump sourceApiVersion to 56.0 or later.

Symptom 2: a new field on a standard object isn't available

sf data query --query "SELECT Id, NewField__c FROM Account"
# INVALID_FIELD: No such column 'NewField__c' on entity 'Account'

If NewField__c was added in API 60.0 but you're querying with 55.0, the field isn't visible. Fix: pass --api-version 60.0:

sf data query --query "..." --api-version 60.0

Symptom 3: legacy CLI commands removed

The sfdx force:source:push command was renamed to sf project deploy start in newer CLI versions. If you upgrade the CLI but your scripts still call sfdx force:source:push, the CLI may bail. The fix: rewrite scripts to use the modern sf commands.

Upgrading the CLI

npm install -g @salesforce/cli
sf --version   # confirm the new version

The CLI updates rapidly — every couple of months. Pin a specific version in CI to avoid surprises:

npm install -g @salesforce/cli@2.42.0

When you can't upgrade

If your team is on an older CLI (organisational decision, security review pending), you can:

  • Pin to an older API version in sourceApiVersion. Newer features are unavailable, but old code continues to work.
  • Use the Metadata API directly for specific operations. Slower but version-independent.
  • Spin up a separate, newer CLI install under a different alias for individual commands that need it.

A subtler gotcha: VS Code Salesforce Extensions

The VS Code extension uses its own bundled CLI. If you have sf installed globally at version 2.42 but the VS Code extension uses 2.10, you might see different behaviour from the same command. Reconcile by setting the extension's CLI path to your global install (Setup → Extensions → Salesforce → Salesforce CLI Path).

Related dictionary terms