Troubleshooting

The panel shows an error about .buttons.json

A buttons file failed to parse (invalid JSON or a validation error). Buttons surfaces the message and treats the file as empty until it’s fixed.

• Open the file with Buttons: Open Project Buttons File or Buttons: Open Global Buttons File and fix the syntax.
• See .buttons.json validation for the exact rules.

The panel is empty or shows no scripts

• Make sure a workspace folder is open (File → Open Folder). A single untitled file has no workspace to scan.
• Check buttons.scriptFiles. If you disabled a file type, its scripts aren’t offered.
• Check the Project scripts tab. Scripts appear there first; you may need to Generate a file or check boxes.

A script shows “not found”

The script reference points at a script that no longer exists in the scan. This happens when a script is renamed or deleted, its file type was disabled, or (since 2.0) its directory is outside the scan scope.

• Run Rescan (or Buttons: Rescan Scripts) to refresh.
• If the file lives outside the project root’s top level (for example after upgrading to 2.0), add its directory in the Scan directories card, recursive for package trees. See Monorepos.
• If the script was renamed, check the newly-discovered script in the Project scripts tab.
• If you removed it deliberately, uncheck or remove the stale button.

Commands aren’t updating after I edit a file

Buttons watches the script files and buttons files and re-renders automatically, but the update is debounced (about 300 ms). If it still looks stale, run Rescan to force a refresh.

Generate deleted my custom commands

It should not. Generate adds any missing root-level scripts and leaves custom commands, notes, variants, and extra opted-in scripts in place. Rescan refreshes commands for scripts you already have. See Generate vs Rescan.

My global buttons aren’t updating immediately

The global ~/.buttons.json is watched with fs.watch because it lives outside the workspace. If the file did not exist when the extension started, Buttons polls for it (every 5 seconds) until it appears, then switches to watching. If you just created the file, give it a moment, or reload the window.

The extension doesn’t appear after install

• Reload VS Code: Ctrl/Cmd+Shift+P → Developer: Reload Window.
• Buttons activates when a workspace contains .buttons.json or on startup (onStartupFinished). If it’s still missing, check that it’s enabled in the Extensions view.

I installed a .vsix but see the old version

Reload the window after code --install-extension and confirm the version in the Extensions view. See local installation.

A terminal named “Buttons” keeps getting reused

Run reuses your active terminal if one is open, otherwise a terminal named Buttons, and only creates one if neither exists. To isolate a command, use New Terminal instead, which always opens a fresh terminal. System is a third option: it opens the OS terminal outside VS Code and leaves the command unrun.