Agent skill

salesforce-known-pitfalls

Identify and avoid Salesforce anti-patterns including SOQL N+1, governor limit violations, and API waste. Use when reviewing Salesforce code for issues, onboarding new developers, or auditing existing Salesforce integrations for best practices violations. Trigger with phrases like "salesforce mistakes", "salesforce anti-patterns", "salesforce pitfalls", "salesforce what not to do", "salesforce code review".

Stars 1,803
Forks 241

Install this agent skill to your Project

npx add-skill https://github.com/jeremylongshore/claude-code-plugins-plus-skills/tree/main/plugins/saas-packs/salesforce-pack/skills/salesforce-known-pitfalls

SKILL.md

Salesforce Known Pitfalls

Overview

The 10 most common and costly mistakes when integrating with Salesforce, with real error messages and correct patterns.

Pitfall #1: SOQL N+1 Query Pattern (Most Common)

Anti-Pattern

typescript
// Query accounts, then query contacts for each = N+1 API calls
const accounts = await conn.query('SELECT Id, Name FROM Account LIMIT 100');
for (const account of accounts.records) {
  // 100 extra API calls! (plus 100 extra SOQL queries in Apex)
  const contacts = await conn.query(
    `SELECT Id, Name, Email FROM Contact WHERE AccountId = '${account.Id}'`
  );
}
// Total: 101 API calls for what should be 1

Correct Pattern

typescript
// Single relationship query — 1 API call
const accounts = await conn.query(`
  SELECT Id, Name,
    (SELECT Id, FirstName, LastName, Email FROM Contacts)
  FROM Account
  LIMIT 100
`);
// accounts.records[0].Contacts.records → child contacts

Pitfall #2: Ignoring API Limits (Org-Wide Shared Pool)

Anti-Pattern

typescript
// This integration uses 80,000 API calls/day
// Sales team uses 60,000/day
// Total: 140,000 > 150,000 limit → everyone gets blocked

Correct Pattern

typescript
// 1. Check limits before batch operations
const limits = await conn.request('/services/data/v59.0/limits/');
if (limits.DailyApiRequests.Remaining < estimatedCalls) {
  throw new Error('Insufficient API calls remaining');
}

// 2. Use sObject Collections (1 call = 200 records)
await conn.sobject('Contact').create(contacts); // batch of up to 200

// 3. Use Bulk API for 10K+ (separate limit pool)
await conn.bulk2.loadAndWaitForResults({ object: 'Contact', operation: 'insert', input: csv });

Pitfall #3: SOQL Injection

Anti-Pattern

typescript
// User input directly in SOQL — injectable
const name = req.query.name; // Could be: "'; SELECT Id FROM User; --"
await conn.query(`SELECT Id FROM Account WHERE Name = '${name}'`);

Correct Pattern

typescript
function escapeSoql(value: string): string {
  return value.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
}
await conn.query(`SELECT Id FROM Account WHERE Name = '${escapeSoql(name)}'`);

Pitfall #4: SELECT FIELDS(ALL) (Performance Killer)

Anti-Pattern

typescript
// Fetches ALL fields — 200+ columns on Account, massive payload
const result = await conn.query('SELECT FIELDS(ALL) FROM Account LIMIT 100');

Correct Pattern

typescript
// Select only what you need — 5-10x faster, much less data transfer
const result = await conn.query('SELECT Id, Name, Industry, AnnualRevenue FROM Account LIMIT 100');

Pitfall #5: Hardcoded Salesforce Record IDs

Anti-Pattern

typescript
// IDs are different across sandbox and production!
const adminProfileId = '00e5f000001abc';     // Works in sandbox...
const queueId = '00G5f000002def';            // ...breaks in production
await conn.sobject('Case').create({ OwnerId: queueId, ProfileId: adminProfileId });

Correct Pattern

typescript
// Look up by name, not by ID
const queue = await conn.query("SELECT Id FROM Group WHERE Name = 'Support Queue' AND Type = 'Queue'");
const queueId = queue.records[0].Id;

const profile = await conn.query("SELECT Id FROM Profile WHERE Name = 'System Administrator'");
const profileId = profile.records[0].Id;

Pitfall #6: Not Handling Partial Success in Bulk Operations

Anti-Pattern

typescript
const results = await conn.sobject('Contact').create(contacts);
console.log('Done!'); // Ignoring that some records may have failed

Correct Pattern

typescript
const results = await conn.sobject('Contact').create(contacts);
const failures = results.filter(r => !r.success);
if (failures.length > 0) {
  console.error(`${failures.length}/${results.length} records failed:`);
  for (const failure of failures) {
    console.error(`  ${failure.errors.map(e => `${e.statusCode}: ${e.message}`).join('; ')}`);
  }
}

Pitfall #7: Using test.salesforce.com for Production

Anti-Pattern

typescript
// Sandbox login URL used for production — silently connects to sandbox
const conn = new jsforce.Connection({
  loginUrl: 'https://test.salesforce.com', // WRONG for production
});

Correct Pattern

typescript
const conn = new jsforce.Connection({
  loginUrl: process.env.SF_LOGIN_URL, // 'https://login.salesforce.com' for prod
  // OR: 'https://test.salesforce.com' for sandboxes
});
// Always use environment variables — never hardcode login URLs

Pitfall #8: Not Using External IDs for Upsert

Anti-Pattern

typescript
// Without External ID: create duplicates on every sync run
await conn.sobject('Account').create({ Name: 'Acme Corp', Industry: 'Tech' });
// Run again → duplicate Account created!

Correct Pattern

typescript
// With External ID: upsert is idempotent — safe to retry
await conn.sobject('Account').upsert({
  External_ID__c: 'CRM-ACME-001',  // Custom External ID field
  Name: 'Acme Corp',
  Industry: 'Tech',
}, 'External_ID__c');
// Run again → updates existing record, no duplicate

Pitfall #9: Missing Error Handling for UNABLE_TO_LOCK_ROW

Anti-Pattern

typescript
// Record locking is COMMON in Salesforce — this crashes on contention
await conn.sobject('Account').update({ Id: accountId, Name: 'New Name' });
// Error: UNABLE_TO_LOCK_ROW → unhandled, crashes the process

Correct Pattern

typescript
async function updateWithRetry(objectType: string, data: any, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await conn.sobject(objectType).update(data);
    } catch (error: any) {
      if (error.errorCode === 'UNABLE_TO_LOCK_ROW' && attempt < maxRetries) {
        await new Promise(r => setTimeout(r, 1000 * attempt)); // Backoff
        continue;
      }
      throw error;
    }
  }
}

Pitfall #10: Polling When CDC Is Available

Anti-Pattern

typescript
// Poll every 5 minutes — wastes 288 API calls/day even when nothing changed
cron.schedule('*/5 * * * *', async () => {
  const changes = await conn.query(`
    SELECT Id, Name FROM Account WHERE LastModifiedDate >= ${fiveMinAgo}
  `);
  // Usually returns 0 records — wasted API call
});

Correct Pattern

typescript
// CDC — only fires when data actually changes, zero wasted API calls
conn.streaming.topic('/data/AccountChangeEvent').subscribe((event) => {
  // Only called when an Account is actually created/updated/deleted
  handleAccountChange(event);
});

Quick Reference Card

Pitfall Detection Prevention
N+1 SOQL queries High API call count, loop with .query() Use relationship SOQL
API limit exhaustion REQUEST_LIMIT_EXCEEDED Monitor /limits/, use Bulk API
SOQL injection String concatenation in .query() Use escapeSoql()
SELECT FIELDS(ALL) Slow queries, large payloads Select only needed fields
Hardcoded IDs Different behavior in sandbox vs prod Query by Name, use External IDs
Partial failure ignored Silent data loss Check .success on every result
Wrong login URL Connected to wrong org Use SF_LOGIN_URL env var
No External ID Duplicate records on re-sync Add External_ID__c, use upsert
No retry for LOCK_ROW Random crashes under load Retry with exponential backoff
Polling over CDC Wasted API calls Use Change Data Capture

Resources

Expand your agent's capabilities with these related and highly-rated skills.

Didn't find tool you were looking for?

Be as detailed as possible for better results