Apex Language Server Could Not Provide Information About Valid Breakpoints | Fix Checklist

You click the gutter, drop a breakpoint, launch Apex Replay Debugger, and then the breakpoint turns grey. You might also see a toast that says the language server can’t provide valid breakpoint info. That’s frustrating because everything else in your setup can look fine—org auth works, deploy works, tests run, and logs download.

Most of the time, this error is not a “debugger is broken” moment. It’s a mapping mismatch. Replay debugging replays a server-side run and then maps that run back to your local files and line numbers. If the Apex Language Server can’t answer “which lines are valid stop points for this exact file version,” VS Code can’t verify breakpoints and the replay session can’t stop where you expect.

Apex Language Server Could Not Provide Information About Valid Breakpoints

When you see apex language server could not provide information about valid breakpoints, it helps to think about what the debugger is asking for. A normal debugger can attach to a running process and stop anywhere the runtime allows. Apex Replay Debugger is different. It replays a debug log and asks the language server to translate that log into a stop map for your local source.

This translation can fail in a few repeat patterns:

• Stale Language Server Index — The local index was built on an older file tree, an older branch, or an older Salesforce release cache.
• Path Or Package Confusion — The same class name appears in more than one package directory, or the project paths don’t normalize the way the debugger expects.
• Log That Can’t Replay Cleanly — The log is truncated, missing detail, or not generated in a replay-friendly way.
• Toolchain Drift — Extensions, CLI, and Java do not line up after updates, so the language server runs but fails breakpoint queries.

Salesforce’s own troubleshooting for the Apex Language Server includes resetting indexing by deleting your project’s .sfdx/tools folder so the language server rebuilds its cache. That reset step is the center of this checklist. Reset Apex Indexing.

Quick Checks Before You Reset Anything

Do these quick checks first. They catch cases where your log and local source can’t ever match, so a cache reset won’t change the outcome.

• Open The Right Folder — In VS Code, open the folder that contains sfdx-project.json. A parent folder can break path resolution.
• Verify The File Is Local — Make sure the class or trigger you’re stepping through exists in your workspace, not only in the org.
• Match The Branch To The Log — If you captured the log on a different branch, line numbers may not align with your current file.
• Pick Executable Lines — Place breakpoints on statement lines, not on braces, comments, annotations, or method signatures.
• Use A Fresh Log — Generate the log right before you replay it. Old logs can map to old code.

If all of that looks right, move on. The next steps rebuild the local index and clean up the path rules that the debugger relies on.

Also peek at VS Code’s Output panel and choose “Apex Language Server”. If it’s still scanning, breakpoint validation can stay grey until the scan finishes. A quick sign is that code completion and “Go to Definition” stop flickering. If your repo is large, give it a short pause after opening the folder and after switching branches. If you jump straight into replay, you can trigger the error even with a clean setup.

Reset The Apex Language Server Index And Cache

This is the fastest fix with the highest hit rate. Stack Exchange answers and multiple issue reports point to clearing the project’s .sfdx/tools cache so the Apex Language Server rebuilds its index cleanly. Cache Reset Thread.

Safe Reset Steps

1. Stop The Debug Session — End the replay session and close the debug log tab.
2. Quit VS Code — Exit fully so extensions release file locks.
3. Delete The Project Cache — Remove .sfdx/tools inside your project folder.
4. Reopen The Project — Start VS Code, then open the same project folder again.
5. Let Indexing Finish — Wait until Apex language features settle before launching replay.

After you reopen the project, open any Apex file and wait until the editor feels settled. If you type a few letters and completion pops in, the language server is alive. If completion stays blank and the status bar shows ongoing work, let it finish. Replay breakpoint checks rely on that same index, so running replay mid-build can bring the message back.

Terminal Commands

Run these only from the root of your Salesforce DX project.

macOS Or Linux

rm -rf .sfdx/tools

Windows PowerShell

Remove-Item -Recurse -Force .sfdx\tools

If the error comes back often, some developers also delete the local index database file inside the numbered release folder under .sfdx/tools (it is often named apex.db). That workaround shows up in the same Stack Exchange thread where the message repeats. apex.db Workaround.

Apex Language Server Valid Breakpoints Error In Multi Package Projects

Multi-package repos add one more failure mode— the debugger can’t resolve file paths the same way your project config does. One GitHub issue reports that a ./ prefix in sfdx-project.json package directory paths can stop the debugger from returning verified breakpoint lines, and removing that prefix fixes it. Path Prefix Issue.

Project Settings That Affect Breakpoints

• Normalize Package Paths — In sfdx-project.json, remove a leading ./ from packageDirectories paths, then reload VS Code.
• Keep One Default Package — Make sure only one directory uses "default": true.
• Avoid Duplicate Class Names — If the same class name exists in two folders, the language server can index both and the debugger may refuse to validate.

Triage Table

What You See	Likely Cause	Try This
Grey breakpoints in one package only	Package path not normalized	Remove ./ prefix, reload, re-index
Some files verify, others never do	Duplicate symbols across folders	Rename one class or open a smaller workspace
Replay loads, but never stops	Local file differs from org version	Pull source from org, then reset cache

After any config change, reload VS Code and wait for indexing. If you start replay while indexing is mid-scan, you can end up back in the same state.

Make Sure Your Replay Log Can Verify Breakpoints

Replay debugging is only as good as the log you feed it. Trailhead’s replay debugger project shows a simple flow—run code, download the log into the project, then launch replay from that log. Replay Debugger Steps.

Trailhead also notes that downloaded logs live under .sfdx/tools/debug/logs inside your project. If you open a log from somewhere else, replay can still start, but you add one more path hop for the debugger to resolve. Keeping the log inside the project folder keeps the mapping step simple.

One-Time Org Setup

1. Set A Trace Flag — In Setup, create a trace flag for the user who will run the transaction.
2. Raise Apex Code Log Level — Use a high Apex Code level so the log contains enough detail to replay.
3. Enable Replay Debug Logging — In VS Code, run the command that turns on debug logging for replay. A Stack Exchange reply points to SFDX: Turn On Apex Debug Log for Replay Debugger when breakpoints never hit. Breakpoint Not Hitting.

Per-Session Routine

• Reproduce The Run — Trigger the transaction or rerun the test right before you grab the log.
• Download The New Log — Use SFDX: Get Apex Debug Logs so it lands under the project’s .sfdx/tools area.
• Launch Replay From The Current Log — Right-click in the log file and launch replay from that file.
• Set Breakpoints After Launch — Place breakpoints after the session starts so validation uses the loaded trace.

If you still see the same message after a cache reset and a fresh log, move to toolchain checks next.

Update And Repair The VS Code Salesforce Toolchain

Apex language features and replay debugging rely on VS Code extensions, Salesforce CLI, and a Java runtime. If one updates and another lags, the language server can start and still fail breakpoint queries. Trailhead lists VS Code, Salesforce CLI, and a JDK as core requirements for the replay debugger setup. Setup Requirements.

Extension And CLI Refresh Steps

1. Update Salesforce Extensions — Update the Salesforce Extension Pack, then restart VS Code.
2. Update Salesforce CLI — Install the latest Salesforce CLI and run sf --version to confirm it’s on your path.
3. Reload The Window — Run “Developer: Reload Window” so extensions restart cleanly.
4. Reauthorize The Org — If CLI commands fail, re-run org auth and set the default org again.

Java Checks

• Use One JDK Path — Point Salesforce’s Java setting to one installed JDK location.
• Avoid Mixed JDK Picks — If your terminal uses one JDK and VS Code uses another, align them and restart VS Code.

If the problem started right after a CLI update, it’s worth scanning the Salesforce VS Code repo for replay debugger reports. One closed issue describes the message appearing after a CLI update during replay runs. Replay Debugger Issue.

Fallback Fixes When Breakpoints Still Won’t Verify

At this point you’ve handled cache, paths, log quality, and tool versions. The last fixes are about making your workspace match the org and the log with as little noise as possible.

Force A Clean Local Match

1. Pull Fresh Source — Retrieve the class or trigger from the org into your project so line numbers match what executed.
2. Replay Only Logs From This Code — Use logs created after the pull, not older ones.
3. Reset Cache Again — Delete .sfdx/tools once more after the pull so indexing uses the new files.

Simplify The Workspace

• Use One Root Folder — Avoid multi-root workspaces while debugging.
• Open A Smaller Slice — If your repo is large, open only the package you’re replaying in a separate window.

Know What Replay Can And Can’t Do

If your log spends most of its time in managed package code, breakpoints in that code may not validate the way you expect. A write-up on replay debugging with managed packages notes that customer-org debugging is not available in Apex Replay Debugger and a different debugger is needed for that case. Managed Package Notes.

When you hit apex language server could not provide information about valid breakpoints, start with the cache reset and path normalization. Then generate a fresh log and confirm CLI, extensions, and Java are aligned. That checklist fixes most setups without a reinstall. If you change package folders often, reset the cache before replay, and keep your log and branch in sync.