How do I troubleshoot Salesforce when I don't know what's wrong?

Walk the 5 layers in order — most teams skip layer 1 and waste hours debugging the wrong layer. (1) Authentication: can the user actually log in, and is the OAuth/SSO/MFA flow producing the right token scopes? (2) API: are API requests succeeding, and are you within rate limits and field-level access? (3) Data sync: is data flowing in/out at the expected pace, and are matching/dedup rules behaving? (4) Workflow: are flows, process builders, and Apex triggers firing in the right order without conflicts? (5) License: does the user actually have the feature license they need, in the right edition? 80% of 'Salesforce is broken' tickets are layer 1, 5, or 4 — not layer 2 or 3 where most teams start.

Why is my Salesforce data not syncing with [external system]?

Five most common causes in priority order. (1) API user permissions — the integration user lost access to a field or object after a permission set change. (2) Rate limit exhaustion — Salesforce has per-org daily API limits that integrations hit during bulk operations. (3) Validation rule blocking writes — a recently-added validation rule is rejecting records that previously synced. (4) Duplicate management rules — the platform's matching rules are silently blocking inserts as 'possible duplicates.' (5) Field-level security on the integration profile — an admin tightened FLS without realizing the integration depended on those fields. Check Setup → API Usage and the Setup → Login History for the integration user FIRST.

What's the fastest way to debug a failed Salesforce flow?

Three steps. (1) Setup → Process Automation → Flows → click into the failed flow → click 'View All Versions' → confirm the active version is the one you think it is. Half of flow debugging discovers an outdated version is active. (2) In the same flow, click 'Open' on the active version → use Debug to step through with sample data — this reveals which decision branch fires + which variable holds what. (3) Setup → Email Logs to see actual flow failure emails (often filtered out of admin inboxes by mail rules) — they include the exact stack trace and failed record IDs.

How do I fix a Salesforce authentication error?

Check in this order. (1) Is MFA enrollment complete for the user? Salesforce silently blocks login when MFA is required-but-not-enrolled. (2) Is the IP address in the user's IP login range? Network changes break this without obvious error messages. (3) Is the OAuth token expired? Refresh tokens expire silently — re-auth the connected app. (4) Is the user's profile/permission-set actually granted access to the API/feature? Profile changes can revoke API access. (5) Is the org sandboxed vs production confusion? Sandbox URLs (test.salesforce.com) reject production credentials and vice versa. Most auth errors are (1) or (5).

Why is my Salesforce report showing wrong numbers?

Four common causes. (1) Report timezone — reports default to user timezone, which differs from the org timezone where data was created. Adjust report timezone explicitly. (2) Field-level security hiding records from the report runner — the runner doesn't see records they don't have access to, but the report shows totals as if they do. (3) Custom report types with incorrect joins — left/inner join differences silently exclude records. (4) Filter logic that combines OR/AND incorrectly — Salesforce's filter logic editor uses 1/2/3 boolean syntax that's easy to misread. Always validate report counts against a SOQL query in Developer Console as ground truth.

How do I troubleshoot Salesforce API rate limits?

Setup → API Usage shows your 24-hour rolling consumption. If you're hitting limits: (1) Identify the heaviest consumer — usually a misconfigured integration that polls instead of subscribing to Platform Events. (2) Convert poll-based integrations to Streaming API or Change Data Capture for real-time updates without burning calls. (3) Use Bulk API 2.0 for batch operations (one bulk job costs much less than thousands of individual calls). (4) Contact your Salesforce account team for a temporary or permanent limit increase if your usage is legitimately growing. Rate limit increases are typically free for valid business reasons.

Should I troubleshoot Salesforce myself or hire an admin?

DIY for symptoms in layers 1, 2, and 4 (auth, API, workflow) — these are usually well-documented Salesforce errors with clear fixes. Hire help for symptoms in layers 3 and 5 (data sync, license) — these often require deep org-specific knowledge of past customizations, and a fractional Salesforce admin saves weeks of guessing. The break-even is roughly: if the issue is blocking revenue and you can't isolate it in 2 hours, hire help. If it's an annoyance, DIY through the 5-layer framework.

What's the most common Salesforce troubleshooting mistake?

Starting with Layer 2 (API) when the issue is in Layer 1 (Authentication) or Layer 5 (License). Engineers default to debugging API requests because that's where they live, but most 'Salesforce broken' tickets are auth or license — a user MFA-locked, a profile permission revoked, an edition that doesn't include the feature. Walking the 5 layers in order surfaces the actual cause in 5 minutes instead of 5 days. Second most common: trusting that the active flow version is the one labeled 'most recent' — always confirm via the Versions panel.

⚙️ Salesforce Troubleshooting · 2026 Operator Read

Salesforce isn't broken.
You're debugging the wrong layer.

Most "Salesforce is broken" tickets aren't where teams think they are. Engineers default to API debugging because that's where they live. The actual cause is usually auth, license, or workflow — and walking the 5 layers in order surfaces it in 5 minutes instead of 5 days.

PJ · Cardiff operator · 858-461-8054

⚡ TL;DR · 60-second read Walk the 5 layers in order before guessing. Layer 1: Auth (MFA enrollment, IP range, OAuth token, sandbox vs prod). Layer 2: API (rate limits, field-level security, validation rules). Layer 3: Data sync (matching rules, dedup, integration user permissions). Layer 4: Workflow (active flow version, debug log, email failure log). Layer 5: License (edition, feature license, user profile). 80% of "Salesforce broken" tickets are layer 1, 5, or 4 — not layer 2 or 3 where most teams start. Quick-fix table + decision tree below cover the most-Googled symptoms.

The 5 layers · walk them in order, not in panic.

Each layer is independently checkable in 60-90 seconds. Walking them in order takes 5 minutes total. Skipping layers is what costs you the day.

LAYER 1

Authentication · can the user actually log in?

The most-skipped layer because "obviously they're logged in." But MFA enrollment, IP range, OAuth token expiry, and sandbox/prod confusion silently break login flows without obvious error messages.

Check: Setup → Login History → filter by user → look at the last 5 attempts. Login Type + Status columns reveal MFA failures, IP blocks, expired tokens, and wrong-org logins instantly.

LAYER 2

API · are requests succeeding within limits?

Where engineers default to debugging. Most "API broken" issues aren't API protocol problems — they're rate limits, field-level security on the integration profile, or validation rules silently rejecting inserts.

Check: Setup → System Overview → API Usage shows your 24h rolling consumption + the heaviest consumers. Setup → API Usage Notifications surfaces hitting limits before they break production.

LAYER 3

Data sync · is data flowing at the expected pace?

Integrations break silently when matching rules, duplicate management, or field-level security on the integration user changes. Records "fail to insert" without obvious error to the upstream system.

Check: Setup → Bulk Data Load Jobs (for bulk integrations) or the integration's own logs. Look for "DUPLICATES_DETECTED", "FIELD_INTEGRITY_EXCEPTION", or "INSUFFICIENT_ACCESS_OR_READONLY" — each maps to a specific Layer 3 root cause.

LAYER 4

Workflow · are flows + Apex firing correctly?

Flows, process builders, and Apex triggers often fire in unexpected order or have outdated active versions. The flow you "fixed" yesterday may not be the version running today.

Check: Setup → Process Automation → Flows → click the flow → click "View All Versions" → confirm the active version is the one you think it is. Use Debug to step through with sample data.

LAYER 5

License · does the user have the feature license they need?

The silent killer. A user can be configured perfectly but lack the feature license that unlocks the functionality. Salesforce's edition + feature-license matrix is unforgiving — Sales Cloud doesn't include Service Cloud features even with admin access.

Check: Setup → Company Information → see your edition + license counts. Then on the user record: "User License" + "Feature Licenses" sections show what THIS user can actually do regardless of profile/permissions.

Quick-fix table · most-Googled Salesforce symptoms.

If you already know your symptom, jump straight to the fix. Each row links to a deeper page with step-by-step instructions.

Symptom	Most likely layer	First check	Deeper fix
Login fails / "Authentication error"	Layer 1 (Auth)	MFA enrolled? IP allowed?	Auth error fix →
API key invalid / 401	Layer 1 + Layer 2	Token expired? Profile changed?	API key fix →
Data not syncing with [external]	Layer 3 (Data sync)	Integration user permissions intact?	Data sync fix →
Duplicate records appearing	Layer 3 (Data sync)	Matching rules + dedup config	Duplicate fix →
Configuration / setup issue	Layer 4 + Layer 5	Profile + permission set + license	Config fix →
Billing / subscription issue	Layer 5 (License)	Edition + feature license counts	Billing fix →
Account suspended	Layer 5 (License)	Org status in Setup	Suspension fix →
Generic "error" with no detail	All layers	Setup → Debug Logs → Apex Errors	Error troubleshooting →
How to fix Salesforce CRM (broad)	All layers	Walk the 5 layers above	Full CRM fix guide →

Decision tree · by what's actually breaking.

If your symptom isn't in the table above, walk this tree. Each branch lands you on the right layer.

Q1: Can the affected user log in at all?
→ No → Layer 1 (Auth): check MFA enrollment, IP range, sandbox vs prod URL.
→ Yes but feature missing → Layer 5 (License): confirm feature license on the user record.

Q2: Is this an API/integration issue?
→ 401/403 errors → Layer 1 (Auth): token expired or profile changed.
→ "Limit exceeded" → Layer 2 (API): rate limits — check API Usage page.
→ "Insufficient access" → Layer 2 (API): field-level security on integration profile.

Q3: Is data appearing/disappearing unexpectedly?
→ Records missing → Layer 3 (Data sync): validation rule or dedup blocking insert.
→ Records duplicated → Layer 3 (Data sync): matching rule disabled or misconfigured.
→ Wrong values in fields → Layer 4 (Workflow): a flow is updating after the integration writes.

Q4: Did a flow or automation stop working?
→ Layer 4 (Workflow): confirm active flow version, check email failure logs, debug with sample data.

Q5: Is the org-level status concerning (lockouts, missing features)?
→ Layer 5 (License): check Setup → Company Information for edition + status. Contact your AE if unclear.

The five anti-patterns that turn 5-minute fixes into 5-day debugging.

Each one looks reasonable until you've burned half a sprint chasing the wrong layer.

✗Starting with API debugging when the issue is auth or license

Engineers default to debugging API requests because it's familiar territory. But most "Salesforce broken" tickets are auth (MFA, IP, token) or license (wrong edition, missing feature license).

✓ Always check Login History + License before opening DevTools. 30 seconds vs 5 hours.

✗Trusting that the "active" flow version is what's actually running

Salesforce doesn't auto-activate the most recent flow version when you save. The version you "deployed" yesterday might still be in Draft while a 6-month-old version runs production.

✓ Always confirm via Setup → Flows → "View All Versions" → check the green Active badge before debugging behavior.

✗Ignoring duplicate management rules silently blocking inserts

Duplicate management can be configured to BLOCK inserts (vs. just warn). Integrations get back a generic "DUPLICATES_DETECTED" error and most teams just log it and move on, leaving records uncreated.

✓ Check Setup → Duplicate Management → Duplicate Rules. Either disable for the integration profile or update the matching rule to be less aggressive.

✗Assuming validation rules apply equally to all profiles

Validation rules can be skipped for specific profiles via formula. A rule blocking the integration user but not admins is invisible until you specifically test as the integration user.

✓ Use "Login as User" in Setup to test as the integration user directly. Or grep validation rule formulas for $Profile.Name references.

✗Calling Salesforce support before checking Setup → System Overview

Most issues are visible in System Overview (API usage, storage, license counts, user logins). Opening a support case before checking adds 24-48 hours minimum.

✓ Setup → System Overview is your first 60 seconds. If it doesn't reveal the issue, then open the case.

Why "Salesforce troubleshooting" is an operator-translation problem.

Salesforce's documentation is exhaustive and operationally useless during an outage. 50+ knowledge base articles per error code, written for general use, not for "I have 30 minutes before this revenue call."

The translation layer is the 5-layer framework. It collapses the entire troubleshooting surface into a 5-minute walk that surfaces the actual cause 80% of the time. Not a feature SaaS vendors sell — operator wisdom from people who've debugged enough Salesforce orgs to recognize the patterns.

This is where operator-grade content beats vendor-grade content. Salesforce can't write this guide because it's a critique of how their docs surface causes. SideGuy can because we don't have that constraint.

Salesforce isn't broken. You're just debugging the wrong layer.
5 minutes of layered checking beats 5 days of guessing.

Stuck on a Salesforce issue?

If you've walked the 5 layers and the issue isn't surfacing, text the actual symptom + which layer you've ruled out. Operator opinion, not Salesforce support. Free either way.

Text PJ · 858-461-8054

Salesforce isn't broken.You're debugging the wrong layer.