If a breakpoint turns into a hollow gray circle in VS Code on your Mac, the debugger could not register it. Start by checking whether the line can execute and whether the active debugger supports that file. Then confirm that the debug session is running the code you are editing. The indicator alone does not identify which cause applies; this sequence narrows it down without guessing at a universal fix. VS Code’s debugging guide describes the hollow circle and its common causes.

Confirm which breakpoint state you are seeing

A filled red circle is an enabled breakpoint; a filled gray circle is disabled. A hollow gray circle means the debugger could not register the breakpoint. VS Code’s documentation names two common reasons: the line has no executable code, or the debugger does not support that source file. Breakpoints that cannot be registered may also appear hollow when a session starts; source edits during a session without live-edit support can cause the same indicator. The exact behavior can vary with the language and debugger extension.

On macOS, open Run and Debug with Shift–Command–D. In its BREAKPOINTS section, locate the relevant entry and confirm it is enabled. This view lets you manage breakpoints, but it does not by itself explain why a debugger rejected one. Keep the editor open at the marked line so you can compare the source location with the file your session is using. VS Code: Debug code

Check whether the line can execute

Move the breakpoint to a line that performs an action, such as a statement inside a function, rather than a blank line, comment, or brace. A breakpoint is useful only where the debugger can stop execution. If the replacement marker becomes a filled red circle after you start the session, the original line likely had no executable code. This is a diagnostic inference from the documented behavior, not a guarantee: support and breakpoint binding depend on the debugger and language.

If the code is generated, transpiled, bundled, or otherwise differs from the file the running program executes, the debugger may need source maps or another language-specific setup to connect the editor location to runtime code. The general VS Code guide does not prescribe one universal configuration for this situation. Check the documentation for the debugger extension and build setup you use before changing mapping settings.

Check the active debugger and session

VS Code includes debugging support for JavaScript, TypeScript, and Node.js. Other languages and runtimes generally need an appropriate debugger extension. Confirm the relevant extension is installed and active, then start a session for the matching language or runtime. If VS Code prompts you to select a debugger, choose the one that matches the program you intend to run. An extension’s documentation defines its supported source files, breakpoint behavior, and launch options. VS Code: Debug code

Press F5 to start debugging, or use Run and Debug to select a configuration. A simple program may run from the active file, but an application with a specific entry point, arguments, environment variables, or attach target may need a launch.json configuration. For an attach setup, make sure the target process is already running in debug mode and that the connection details match. A correctly placed breakpoint in a file different from the program’s loaded source can remain unverified. VS Code: Configure debugging

Narrow down the cause with a short sequence

Use this order, changing one thing at a time so the result is informative:

  1. In BREAKPOINTS, verify the breakpoint is enabled and note its file and line.
  2. Move it to an executable statement in that file.
  3. Start the intended debug configuration with F5 and see whether the marker registers.
  4. If it stays hollow, verify that the selected debugger supports the file and that its extension is installed and active.
  5. Check that the configuration launches or attaches to the program built from the source you are viewing. Review its entry point, working directory, and any build or pre-launch task relevant to your project.
  6. If the application transforms the source, consult the language debugger’s instructions for mapping editor files to runtime code.

A successful check does not prove every breakpoint in a project is valid; repeat the check at the particular source location. If the debugger reports a configuration or registration error, use that message and the extension’s documentation to guide the next change. Avoid copying settings for a different debugger: VS Code notes that configuration properties and capabilities depend on the selected debugger and request type. VS Code: Configure debugging

What the indicator can and cannot tell you

The hollow circle tells you that the debugger has not registered that breakpoint. It cannot, by itself, distinguish a non-executable line from unsupported source, a mismatch between editor and runtime code, or other debugger-specific limitations. The most useful next step is to test a clearly executable line in the intended session, then verify the debugger and source mapping if registration still fails. On Mac, the core controls are the same VS Code editor gutter, Run and Debug view, F5, and Shift–Command–D; debugger-specific fixes must come from the extension or runtime documentation.

Sources