name: salesforce-common-errors description: 'Diagnose and fix Salesforce common errors, SOQL issues, and API exceptions.

Use when encountering Salesforce errors, debugging failed requests,

or troubleshooting integration issues.

Trigger with phrases like "salesforce error", "fix salesforce",

"salesforce not working", "debug salesforce", "SOQL error", "salesforce exception".

' allowed-tools: Read, Grep, Bash(curl:), Bash(sf:) version: 1.0.0 license: MIT author: Jeremy Longshore jeremy@intentsolutions.io tags:

• saas
• crm
• salesforce compatibility: Designed for Claude Code

Salesforce Common Errors

Overview

Quick reference for the most common Salesforce API errors with real error codes, messages, and solutions.

Prerequisites

• Salesforce connection established (jsforce or simple-salesforce)
• Access to Setup in your Salesforce org
• Familiarity with sObject field API names

Instructions

Step 1: Identify the Error

Check the errorCode field in the API response or the exception from jsforce.

Step 2: Match to Error Below

INVALID_LOGIN — Authentication Failed

[{"message":"INVALID_LOGIN: Invalid username, password, security token; or user locked out.","errorCode":"INVALID_LOGIN"}]

Cause: Wrong credentials or security token. Solution:

# Reset security token: Setup > My Personal Information > Reset My Security Token
# Append token to password: password + securityToken
# Verify IP is whitelisted or token is appended
echo "Password format: ${SF_PASSWORD}${SF_SECURITY_TOKEN}"

INVALID_FIELD — Wrong Field Name in SOQL

[{"message":"SELECT Id, FullName FROM Account\n                ^\nERROR: No such column 'FullName' on entity 'Account'","errorCode":"INVALID_FIELD"}]

Cause: Field API name does not exist on the sObject. Solution:

// Check available fields via describe
const meta = await conn.sobject('Account').describe();
const fieldNames = meta.fields.map(f => f.name);
console.log('Available fields:', fieldNames.join(', '));
// Common mistake: "FullName" vs "Name", "Email" on Account (doesn't exist — it's on Contact)

MALFORMED_QUERY — SOQL Syntax Error

[{"message":"unexpected token: 'FORM'","errorCode":"MALFORMED_QUERY"}]

Cause: Typo in SOQL keywords or missing quotes. Solution:

-- Wrong: SELECT Id FORM Account (typo)
-- Right: SELECT Id FROM Account

-- Wrong: WHERE Name = Acme (missing quotes)
-- Right: WHERE Name = 'Acme'

-- Wrong: WHERE CreatedDate > 2026-01-01 (needs literal format)
-- Right: WHERE CreatedDate > 2026-01-01T00:00:00Z

REQUIRED_FIELD_MISSING — Missing Required Fields on Create

[{"message":"Required fields are missing: [LastName]","errorCode":"REQUIRED_FIELD_MISSING","fields":["LastName"]}]

Cause: Create/update missing a required field. Solution:

// Check required fields
const meta = await conn.sobject('Contact').describe();
const required = meta.fields
  .filter(f => !f.nillable && !f.defaultedOnCreate && f.createable)
  .map(f => f.name);
console.log('Required for create:', required);
// Contact requires: LastName
// Lead requires: LastName, Company
// Opportunity requires: Name, StageName, CloseDate

INSUFFICIENT_ACCESS_OR_READONLY — Permission Issue

[{"message":"Insufficient access rights on cross-reference id","errorCode":"INSUFFICIENT_ACCESS_OR_READONLY"}]

Cause: User profile lacks CRUD permission or field-level security blocks access. Solution: In Setup, check:

1. Profile > Object Permissions > verify CRUD for the sObject
2. Profile > Field-Level Security > verify field access
3. Sharing Rules if record-level access is denied
4. Organization-Wide Defaults (OWD) for the object

REQUEST_LIMIT_EXCEEDED — API Limit Hit

[{"message":"TotalRequests Limit exceeded.","errorCode":"REQUEST_LIMIT_EXCEEDED"}]

Cause: Org exceeded the 24-hour rolling API call limit. Solution:

// Check remaining API calls
const limits = await conn.request('/services/data/v59.0/limits/');
console.log('Daily API:', limits.DailyApiRequests);
// { Max: 100000, Remaining: 45230 }

// Enterprise Edition base: 100,000/24hr + 1,000 per user license
// Check: Setup > Company Information > API Requests, Last 24 Hours

UNABLE_TO_LOCK_ROW — Record Locking Conflict

[{"message":"unable to obtain exclusive access to this record","errorCode":"UNABLE_TO_LOCK_ROW"}]

Cause: Another process is updating the same record simultaneously. Solution: Retry with exponential backoff — this is transient.

// This commonly occurs with triggers, workflows, or parallel bulk jobs
// Retry 3 times with increasing delay
await withRetry(() => conn.sobject('Account').update({ Id: id, Name: 'New Name' }));

DUPLICATES_DETECTED — Duplicate Rule Triggered

[{"message":"Use one of these records?","errorCode":"DUPLICATES_DETECTED"}]

Cause: Salesforce Duplicate Rules matched existing records. Solution:

// Allow duplicates by setting header
const result = await conn.sobject('Lead').create(
  { LastName: 'Smith', Company: 'Acme', Email: 'smith@acme.com' },
  { headers: { 'Sforce-Duplicate-Rule-Header': 'allowSave=true' } }
);

FIELD_CUSTOM_VALIDATION_EXCEPTION — Validation Rule Failed

[{"message":"Phone number must be 10 digits","errorCode":"FIELD_CUSTOM_VALIDATION_EXCEPTION"}]

Cause: A validation rule on the sObject rejected the data. Solution: Check Setup > Object Manager > [Object] > Validation Rules to see active rules and fix your data accordingly.

ENTITY_IS_DELETED — Record in Recycle Bin

[{"message":"entity is deleted","errorCode":"ENTITY_IS_DELETED"}]

Cause: Record was soft-deleted and is in the Recycle Bin. Solution:

-- Query deleted records with ALL ROWS
SELECT Id, Name, IsDeleted FROM Account WHERE Id = '001xx' ALL ROWS

-- Undelete via API

await conn.sobject('Account').undelete('001xxxxxxxxxxxx');

Quick Diagnostic Commands

# Check Salesforce system status
curl -s https://api.status.salesforce.com/v1/instances | jq '.[0]'

# Check org API limits via sf CLI
sf org display --target-org my-org

# List recent API errors in debug log
sf apex log list --target-org my-org
sf apex log get --log-id 07Lxx --target-org my-org

Error Handling

Resources

• Salesforce Status API
• REST API Error Responses
• SOQL Date Literals
• Salesforce Governor Limits

Next Steps

For comprehensive debugging, see salesforce-debug-bundle.