[Common Troubleshooting] A Summary of Common Errors in VSCode and How to Solve Them

Hello! I'm someone who went from zero programming knowledge to launching a website by myself with the help of AI. I understand your "I don't get it" moments perfectly. Because just a few months ago, I was in the exact same spot, scratching my head.

Especially when you're just starting with VSCode (Visual Studio Code), the endless stream of error messages can be really disheartening, right? You just think, "I just want to write some code...!"

In this article, I'll explain the most common errors I actually encountered and overcame in VSCode, breaking down the solutions in a way that's easier to understand than anywhere else, avoiding jargon as much as possible. The goal is simple: to help you experience that "It works!" moment. After reading this, errors won't be scary anymore. Let's solve them together, one by one!

[The Absolute Basics] The Three Sacred Treasures of Troubleshooting to Try First!

Before we get into specific errors, there are some "fundamentals" I want you to try first, no matter what problem you're facing. You'd be surprised how many issues can be resolved with just these steps.

1. First and Foremost, "Restart"

It might be hard to believe, but this is the most effective solution. If you think "Something's wrong," first, completely close VSCode and then open it again. If an extension failed to load or it's just a temporary glitch, this often fixes it in a snap. It's just like restarting your computer when it's acting up.

2. Temporarily Disable All Extensions

VSCode is so useful thanks to its convenient "extensions." However, sometimes these extensions can conflict with each other and cause unexpected errors.

To check if an extension is the cause, the "Extension Bisect" feature is very helpful.

Open the Command Palette (mac: Cmd + Shift + P, Win: Ctrl + Shift + P).
Type >Extensions: Bisect and run it.
Follow the on-screen instructions, and VSCode will automatically disable extensions by half, helping you identify the problematic extension.

If this solves the problem, then one of your extensions is the culprit. Once you find the problematic extension, either disable it or review its settings.

3. Isolate the Problem

Try to remember "since when" and "after what action" this error started appearing.

Right after installing a new extension?
Only when opening a specific file?
It's fine with HTML files, but the error appears in JavaScript files?

Being able to identify the conditions under which the problem occurs is a shortcut to solving it.

[By Scene] The Errors That Made Me Cry... Common Problems and Copy-Paste Solutions

From here, I'll introduce specific errors that I actually encountered during my website development and that took me a while to solve. I'm sure you'll find the error that's on your screen right now.

Case 1: Garbled Text! The "Mojibake" Error

You thought you wrote Japanese in your HTML file, but when you view it in the browser, it turns into mysterious symbols like ï¿½ï¿½ï¿½... This is a "mojibake" (garbled text) error, a path every beginner must walk.

Cause:
This is caused by a mismatch between the "character encoding" the file is saved in and the character encoding the browser assumes it's written in. In the past, formats like Shift_JIS were common in Japan, but now the global standard is UTF-8.

Solution:
Let's change the VSCode settings to save all future files in UTF-8. Once you set this, you'll never have to worry about garbled text again.

On mac, press Cmd + , (comma), and on Windows, press Ctrl + , (comma) to open the settings. Then, click the file icon in the top right to open settings.json and paste the following code.

{
  // File-related settings
  "files.encoding": "utf8", // Set the default character encoding to UTF-8 when opening files
  "files.autoGuessEncoding": true, // Automatically guess character encoding when opening files
  "files.eol": "\n" // Unify the line ending to LF (\n)
}

If there's already something written inside the {}, just add the setting items (like "files.encoding": "utf8",) inside.

Case 2: Command Not Working! The "command not found" Error

In web development, you often use commands like npm and git in VSCode's built-in terminal. However, sometimes when you type a command, you get an error like zsh: command not found: npm, as if it's telling you "I don't know that command."

Cause:
This is because the command (program) is not installed on your computer, or it is installed, but your computer doesn't know where it is (i.e., the PATH is not set).

Solution:
First, let's check if it's actually installed. For example, for Node.js (which includes the npm command), try typing the following command in the terminal.

node -v

If a version number (e.g., v20.11.0) is displayed, it's installed. If you get command not found, it means it's not installed at all. Install it from the official Node.js website.

If you still get the error even though it's installed, try restarting VSCode. Immediately after installation, VSCode may not have recognized the new PATH.

Case 3: Code Not Formatting! Prettier / ESLint Not Working

The moment you save a file, your messy code is magically formatted... This is made possible by formatters/linters like Prettier and ESLint. But a common frustration is when you've set it up, but it's not working at all!

Cause:
There are several possible reasons.
1. The Prettier or ESLint extension for VSCode is not installed or is disabled.
2. The project is missing configuration files (.prettierrc, .eslintrc.js).
3. "Format on Save" is not enabled in VSCode settings.
4. Multiple formatters are conflicting.

Solution:
Try copying and pasting the following settings into the settings.json file we mentioned earlier. This is an "all-in-one" configuration that should solve all sorts of problems. This setup saved me countless times when I was building my website.

{
  // ----- Settings for Formatting and Linting -----

  // Set Prettier as the default formatter
  // This prevents conflicts with other formatters
  "editor.defaultFormatter": "esbenp.prettier-vscode",

  // Automatically run formatting on file save
  "editor.formatOnSave": true,

  // Specify file types for ESLint to check and fix
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact"
  ],

  // Also run ESLint auto-fix on file save
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  }
}

【Key Point】
The most important part is "editor.defaultFormatter": "esbenp.prettier-vscode". VSCode has its own built-in code formatting capabilities. Therefore, when you install the Prettier extension, it can get confused about whose instructions to follow. This one line declares, "When it comes to formatting, I'll leave it all to Mr. Prettier!" which prevents conflicts.

Of course, this assumes you have the Prettier and ESLint extensions installed!

Case 4: Import Not Found! The "Cannot find module" Error

When developing with JavaScript or TypeScript, you use import to load components (modules) from other files. Sometimes you might get an error like Cannot find module './components/Button'.

Cause:
This is almost always a simple path specification mistake. However, as projects get more complex, relative paths like ../../../../utils/helper.js can get deeper and deeper, making them easy to get wrong (I call this the "('../') Hell").

Solution:
To escape this "('../') Hell," let's create a configuration file called jsconfig.json (or tsconfig.json for TypeScript). This file tells VSCode, "This is the base location (root) of the project."

Create a file named jsconfig.json at the top level of your project (the same level as package.json) and paste the following content.

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  },
  "exclude": ["node_modules"]
}

【Key Point】
What's so great about this setup? For example, let's say you want to import a file from src/components/ui/Button.jsx into src/pages/index.js, which is in a completely different directory.

Before: import Button from '../../components/ui/Button'; (Easy to get the path wrong...)
After: import Button from '@/components/ui/Button'; (@ points to the src folder, so you can always write it the same way!)

With this, you'll hardly ever need to modify your import statements even if you move files around. This is truly revolutionary!

[Advanced] Don't Be Scared Anymore! How to Ask AI When You Get an Error

The reason I was able to build a website by myself from scratch is undoubtedly thanks to AI assistants. Even if you get an error message, there's no need to panic. It's the best "material" for asking AI a question.

But just copying and pasting the error message won't always get you a good answer. There's a trick to asking questions to get good answers.

The Ultimate Question Template

When you encounter an error, try asking the AI using the following template.

Subject: Encountered [Error Content] in [Technology Used]

1. Background/Goal:
(e.g., I am trying to import a component using Next.js and TypeScript.)

2. Problem Occurring:
(e.g., When I run npm run dev, the following error message is displayed in the terminal.)

Paste the error message here exactly as it is

3. Relevant Code:
(e.g., Here is the relevant part of the code from the file where the error is occurring.)

Paste the code here

4. What I've Tried:
(e.g., I have tried re-running npm install and restarting VSCode, but it did not solve the problem.)

5. Question:
Please tell me the root cause of this error and the specific steps to resolve it.

By conveying "what you were trying to do," "what happened," and "what you've tried" as a set, the AI can accurately understand the situation and provide a precise solution. Error logs are a treasure trove of hints. By all means, make AI your ultimate sidekick.

Summary

In this article, I've explained the common errors that beginners stumble upon in VSCode and their specific solutions, based on my own experiences.

Errors are an unavoidable part of learning to program. But every single error has a cause and a way to be solved. An error message is not your enemy; it's a friendly sign telling you, "This part is wrong!"

I would be overjoyed if this article helps turn your "I don't get it" into "I got it!". Every time you overcome an error, you are definitely leveling up. Be confident and enjoy coding!