WebStorm Client-Side Breakpoints Not Hitting: Diagnostic Guide

Recognizable Condition

You set a breakpoint in TypeScript or JavaScript source, start a JavaScript Debug session, and the gutter marker stays hollow or gray. The tooltip reads "Breakpoint not verified" or the code simply runs past the line without suspending. This happens in WebStorm 2023.x through 2024.x when debugging client-side applications served by Vite, webpack, or a static server.

Cause and Diagnostic Quick-Reference

Ordered Diagnostic Checks

1. Match the run-configuration URL exactly. In Run → Edit Configurations → JavaScript Debug, the URL field must match the locally served address including protocol, port, and base path (e.g., http://localhost:5173/app/). A trailing slash mismatch or http vs https difference breaks mapping.
2. Confirm source maps exist in served output. Open the page in Chrome, press F12, go to Sources tab, and look for webpack://, vite://, or original TypeScript paths. If only minified bundles appear, enable sourceMap: true in tsconfig.json or build.sourcemap: true in vite.config.ts, rebuild, and restart the debug session.
3. Install and enable the JetBrains IDE Support extension. Install from Chrome Web Store or Firefox Add-ons. After installation, click the extension icon on the debugged page and ensure "Allow access to this site" is granted. Restart the JavaScript Debug session after any permission change.
4. Clear browser cache and restart the IDE. Stale service workers or cached bundles without maps can persist. Use DevTools → Application → Clear storage, then restart WebStorm and launch a fresh debug session.
5. Check for multiple debug ports. If Vite or webpack-dev-server prints multiple URLs (e.g., IPv4 and IPv6), ensure the run configuration uses the same hostname the browser opens. Prefer localhost over 127.0.0.1 or [::1] for consistency.

Fixes Tied to Findings

Missing Source Maps

For TypeScript projects, ensure tsconfig.json includes:

{
  "compilerOptions": {
    "sourceMap": true,
    "inlineSources": true
  }
}

For Vite, set build: { sourcemap: true } in vite.config.ts. For webpack, use devtool: 'source-map' in development mode. Rebuild and verify .js.map files appear alongside bundles in the network tab.

Incorrect Remote URL Mapping

In the JavaScript Debug configuration, the "Remote URL" field (labeled "URL" in 2024.x) must map the served root to the project root. Example: if the app serves at http://localhost:3000/dist/ and your project root maps to /dist, set Remote URL to http://localhost:3000/dist/ and Local Root to the project folder containing dist. Mismatched path prefixes cause breakpoints to bind to non-existent script URLs.

Extension Not Active

Install "JetBrains IDE Support" from the browser store. In Chrome, navigate to chrome://extensions, find the extension, enable "Allow access to file URLs" if debugging local files, and set site access to "On all sites" or the specific origin. The extension icon should show a green dot when a debug session is active.

Escalation Criteria

If breakpoints remain unverified after completing all five checks, collect diagnostic data before contacting JetBrains support:

1. In WebStorm, choose Help → Collect Logs and Diagnostic Data.
2. Reproduce the failure once more with the log collection running.
3. Attach the resulting archive with a minimal reproducible project (single HTML + TS file, Vite config, run configuration) to a YouTrack issue or support ticket.

Include WebStorm version (Help → About), browser version, and whether the issue occurs in a clean profile.

Version-Sensitive Notes

• WebStorm 2023.3 moved the "Remote URL" field into the main configuration pane; earlier versions placed it under a "Mappings" tab.
• 2024.1+ auto-detects Vite and webpack-dev-server URLs when you click the browser icon in the run dashboard; verify the detected URL before relying on it.
• Production builds often strip source maps or inline them as data URLs. Debug against development builds only.

Verification Checklist

• Run configuration URL matches browser address bar exactly.
• Breakpoints turn solid red within 2 seconds of page load.
• DevTools Sources panel shows original TypeScript/JavaScript files under webpack:// or vite://.
• Stepping works: F8 steps over, F7 steps into, variables panel shows local scope.