Troubleshooting: Salesforce “Sandbox” sync lag after Deployment

Following a metadata deployment using CI/CD pipelines, the Salesforce CLI (sf), DevOps Center, or Change Sets, sandboxes frequently suffer from “sync lag.” A deployment may show as successful in your deployment history, yet updated fields, page layouts, Flow versions, or Apex classes do not appear on record pages or return stale definitions in API queries. This condition is caused by background compilation delays, persistent client-side caching, or desynchronized local source tracking.

Fast Fix

Confirm in Setup > Deployment Status that the deployment job and all post-deployment apex compilation queues are marked completed. To clear client-side rendering lag immediately, go to Setup > Session Settings, temporarily uncheck “Enable secure and persistent browser caching to improve performance,” save, and perform a hard browser refresh (Ctrl + F5 or Cmd + Shift + R).

---

Diagnostic Snapshot

• Observed Behaviors: Metadata deployed successfully, but UI displays older layouts; Lightning Web Components execute stale logic; CLI returns No changes found to deploy/retrieve.
• Underlying Mechanisms: Lightning Client-Side Caching, delayed background Apex bytecode compilation, out-of-sync local CLI source tracking files, or asynchronous metadata indexing.
• Affected Tools: Salesforce CLI (sf), GitHub Actions / Jenkins pipelines, Salesforce DevOps Center, Changesets, and Developer Console.
• Permissions Required: System Administrator access to edit Session Settings and compile Apex classes.

---

Why Sandboxes Experience Post-Deployment Lag

Unlike Production environments—which prioritize instantaneous infrastructure cache invalidation—sandbox instances share multi-tenant compute resources with lower processing priorities.

Lag typically stems from three isolated layers:

1. Client Browser Cache (Aura/LWC Framework Cache): Salesforce aggressively caches component definitions and metadata layouts in your browser’s IndexedDB and localStorage to reduce server calls.
2. Platform Bytecode Compilation Queues: When Apex classes or triggers are deployed, Salesforce flags dependent code as uncompiled. It compiles them into bytecode asynchronously in the background. Until compilation finishes, components relying on those classes may fail or serve cached responses.
3. Source Tracking Desynchronization: If you are developing locally using the Salesforce CLI, your project maintains an internal tracking file. If a remote deployment happens outside your CLI session, the local tracking table becomes blind to remote sandbox changes.

---

Diagnostic Path

Deployed Changes Not Appearing in Sandbox
 ├── Check Setup ──► Deployment Status
 │    ├── Status = "In Progress" or "Queued" ──► Wait for deployment queue to clear
 │    └── Status = "Succeeded"
 │         ├── Is it an Apex / Automation change?
 │         │    └── Action: Run "Compile all classes" in Setup
 │         ├── Is it a Page Layout / LWC change?
 │         │    └── Action: Clear browser storage / disable persistent caching
 │         └── Is it a local CLI / VS Code discrepancy?
 │              └── Action: Reset project tracking via sf project reset tracking

---

Step-by-Step Resolution

Step 1: Verify Deployment Queue and Asynchronous Status

1. Navigate to Setup > enter Deployment Status in the Quick Find box.
2. Locate your recent deployment job.
3. Confirm that the status is Succeeded.
4. If the status is stuck at Processing or queued behind a long-running batch deployment, the metadata has not yet been committed to the sandbox database. If your deployments consistently stall or time out at this stage, see Fix: Salesforce “Metadata API” Timeout during large Package Deployment.

Step 2: Force Server-Side Apex Recompilation

When classes or triggers are deployed across complex codebases, the platform marks downstream dependencies “invalid” until they are recompiled.

1. In Setup, search for Apex Classes.
2. Click the link labeled Compile all classes.
3. Wait for the compilation job to complete. This forces the platform to re-index all dependencies, ensuring that API calls and UI controllers execute the latest deployed code rather than uncompiled references.

Step 3: Clear Browser and Framework Cache

If code has deployed but Lightning Experience continues rendering old page layouts or outdated LWC interfaces:

1. In Salesforce Setup, go to Session Settings.
2. Scroll to the Caching header.
3. Uncheck the box: “Enable secure and persistent browser caching to improve performance”.
4. Click Save at the bottom of the page.
5. In your browser, open Developer Tools (F12), right-click the browser refresh button, and select Empty Cache and Hard Reload.
6. Verify your updated metadata in the UI.
   (Note: Re-enable persistent caching once verification is complete to maintain optimal UI performance).

Step 4: Fix Local CLI Source Tracking Desynchronization

If developers use VS Code and the Salesforce CLI, running sf project deploy start may output No changes detected even though metadata was pushed to the sandbox by another team member or CI/CD branch.

To synchronize local tracking with the actual sandbox state:

1. Open your terminal in the project directory.
2. Clear the local tracking cache: sf project reset tracking --target-org my-sandbox-alias
3. Retrieve the full schema definition directly from the sandbox: sf project retrieve start --metadata CustomObject --target-org my-sandbox-alias

This resynchronizes the local .sf/orgs tracking metadata with the active sandbox schema.

Step 5: Validate Field-Level Security (FLS) on Newly Deployed Fields

A very common misdiagnosis occurs when custom fields or components deploy successfully, but users (including admins) cannot see them.

• The Cause: If a deployment tool does not explicitly deploy permissions profiles or permission sets alongside the fields, the fields default to hidden for all profiles.
• The Check: Open Object Manager > select the Object > Fields & Relationships > click the new field > Set Field-Level Security. Ensure the appropriate profiles have Visible checked. If users are trapped in permission loops after metadata updates, review Fix: Salesforce “You do not have the required permissions” (Identity Loop).

---

Common Misdiagnoses

• Sandbox Refreshes vs. Metadata Deployments: Do not confuse deployment lag with sandbox refresh lag. A sandbox refresh builds an entirely new org instance and can invalidate custom URLs or settings. If links or buttons are returning missing page errors after a refresh event, see Fix: Salesforce “URL No Longer Exists” after Sandbox Refresh.
• Integration Middleware Sync Queues: If an external system (such as HubSpot or an ERP) fails to see newly deployed Salesforce fields, the lag often resides within the middleware’s cached schema rather than Salesforce. Clear the schema cache inside your integration platform or check Troubleshooting: CRM “Sync Queue” Backlog – Resolving 4-hour delays.

---

Hard Stops

• Never perform a manual deployment to override a CI/CD pipeline while automated validation is in flight. Stacking conflicting metadata deployments on a single sandbox risks corrupting the Deployment Queue, which can lock the org’s Metadata API until Salesforce Support intervenes.
• If a deployment status displays “Succeeded” but system components throw critical errors across all users, inspect your automated tests. If test coverage was bypassed during a quick-deploy, an unhandled runtime bug may be crashing components rather than a caching delay.