How to fix INSUFFICIENT_ACCESS in Salesforce deployments

The user or integration making the API call doesn't have the object or field-level permissions the operation requires.

Surfaces during: runtime API calls, both REST/SOAP data operations and connected-app requests

What it means

INSUFFICIENT_ACCESS means the calling user, often an integration or CI service account rather than a person, doesn't have the object permission or field-level security needed to complete the request. It's a permissions failure rather than a data problem: the record and the operation are both valid, but the credential running it isn't authorized for it.

Because it covers the connected app and OAuth layer as well as object CRUD, it's the broadest of the access-related error codes; INSUFFICIENT_ACCESS_OR_READONLY and INSUFFICIENT_ACCESS_ON_CROSS_REFERENCE_ENTITY are both narrower, DML-specific variants of the same underlying idea.

Diagnosis

Common causes

Integration user's profile lacks object access

The service account running the pipeline was never granted access to the object the deployment's data step writes to.

Field-level security wasn't updated for a new field

A permission set used by the CI service account wasn't updated when a new required field was added to the object.

Connected app scope or IP restriction blocked the call

The OAuth scope on the connected app doesn't cover the operation, or an IP range restriction rejected the calling context.

The fix

Audit the integration user's permission sets
Confirm the account executing deployments has explicit object and field-level access for everything the pipeline touches.
Grant FLS on new fields to CI permission sets
Add field-level security for newly created fields to whichever permission set the pipeline's service account uses.
Review connected app OAuth scopes and IP policies
Check that the scopes and IP relaxation settings on the connected app cover the operation being attempted.

In practice

How Serpent prevents this

Serpent runs deployments through a scoped connection to each org, so a permission gap shows up as a clear failure on the task, rather than a silent partial deploy discovered later. See the Salesforce deployment error library.

Approval and audit traceability in Serpent

Prevention

Scope connected app permissions to exactly what the integration needs

Grant the minimum OAuth scopes and object access the integration genuinely uses, then expand deliberately as new fields or objects are added, rather than starting broad.

Add new fields to the integration permission set in the same deployment

Update the CI service account's field-level security as part of the same change that adds a required field, not a follow-up task.

Keep connected app IP restrictions current with your CI provider

Track your CI/CD provider's published IP ranges and update the connected app's trusted IPs before they rotate, not after a run fails.

Common questions

INSUFFICIENT_ACCESS, answered

Is INSUFFICIENT_ACCESS the same as a metadata deploy permission error?

It's related but distinct. This error is about the calling user's runtime object or field access on a record operation, not about who can deploy metadata changes to the org.

Can an IP restriction cause this error even with correct object permissions?

Yes. If the connected app or profile has login IP ranges configured and the calling context falls outside them, Salesforce rejects the request before object permissions are even evaluated.

Does OAuth scope matter if the user's profile already has full access?

Yes. OAuth scopes and profile permissions are enforced independently; a connected app missing the api or full scope can block a call even for a System Administrator user.

Start free. No credit card, no install, no commitment.

Set up in under 15 minutes. No DevOps hire needed.

Start free Book a demo