Troubleshooting & Platform Notes

Due to the nature of modifying VS Code's core files, you may encounter permission issues or warnings. This guide covers the most common problems and their solutions.

VS Code Warns That It Is 'Corrupted'

Symptom: After enabling the extension and restarting, a notification appears with the message: "Your Code installation appears to be corrupt. Please reinstall."

Cause: This is expected. Visual Studio Code performs a checksum on its core files at startup to detect modifications. Because this extension intentionally modifies workbench.html, the checksum fails, and VS Code flags the installation as "corrupted".

Solution:

  1. Recommended: Simply click the "Don't show again" button on the notification. The message is harmless.
  2. Alternative: Install the Fix VSCode Checksums Next extension. This tool will silently patch the checksum verification logic in VS Code, preventing the warning from appearing at all.

Windows: Administrator Permissions

Symptom: The Enable or Disable command fails, and a message appears telling you to "Run VS Code with admin privileges."

Cause: On Windows, VS Code is typically installed in C:\Program Files, a directory that requires administrator permissions to modify.

Solution:

  1. Close Visual Studio Code completely.
  2. Right-click the VS Code icon.
  3. Select "Run as administrator".
  4. Once VS Code has launched with elevated permissions, run the Enable Custom CSS and JS command again.

You only need to run as administrator when enabling, disabling, or reloading customizations. For normal daily use, you can launch VS Code as a standard user.

macOS & Linux: File Permissions

Symptom: The Enable or Disable command fails, possibly without a specific error message, or with a generic filesystem error.

Cause: The user account you are running VS Code with does not have write permissions for the VS Code installation directory.

Solution:

You need to take ownership of the VS Code installation directory. Open your terminal and run the following command, adjusting the path if necessary:

sudo chown -R $(whoami) <Path to Visual Studio Code>

Common Paths for <Path to Visual Studio Code>:

  • macOS (Stable): /Applications/Visual Studio Code.app
  • macOS (Insiders): /Applications/Visual Studio Code - Insiders.app
  • Most Linux Distributions: /usr/share/code
  • Arch Linux: /opt/visual-studio-code or /usr/lib/code/

If you are unsure of the path, you can often find it with which code.