Fix ‘preLaunchTask build Terminated with Exit Code 1’ When Debugging C++ in VS Code

You press F5 to debug your C++ program in VS Code, expecting a breakpoint, and instead a message appears: “preLaunchTask ‘build’ terminated with exit code 1.” The debugger never starts, and the actual reason is hidden one click away. This error simply means the build task that runs before debugging failed, so VS Code refuses to launch a program that was never compiled. Something in your code or your build setup needs attention first.

This guide shows you how to reveal the real error hiding behind that message, how to fix the most common causes, and how to check your tasks and launch files so the problem does not keep coming back.

Quick Answer

The message “preLaunchTask ‘build’ terminated with exit code 1” means the build task linked to your debug configuration failed, usually because your C++ code has a compile error or because the task points at the wrong file or compiler. Click Show Errors or open the terminal output of the build task to see the real compiler message, fix that first error, and make sure the preLaunchTask name in launch.json exactly matches the label in tasks.json.

What a preLaunchTask Actually Does

When you start debugging, VS Code reads your launch.json file to learn how to run the program. Many C++ configurations include a line like "preLaunchTask": "build", which tells VS Code: before starting the debugger, run the task labelled build, because debugging an old executable makes no sense. That task, defined in tasks.json, normally calls your compiler, for example g++, on the current file.

Exit code 1 is the task’s way of saying the command failed. VS Code then stops and shows the message you saw. The debugger itself is almost never the problem; it simply never got a fresh program to debug. Closely related editor confusion, such as squiggles on code that compiles, is covered in our guide to fixing red squiggles on correct C++ code in VS Code.

Step 1: See the Real Error Message

The popup hides the details, so dig them out:

1. When the error appears, choose Show Errors if offered, or open the Problems panel with Ctrl+Shift+M.
2. Alternatively, run the build task yourself with Terminal > Run Build Task and read the terminal output directly.
3. Read the compiler output from the top. The first error is the real one; later lines are usually consequences.
4. Note the file name and line number it mentions, and open that location.

Nine times out of ten you will find an ordinary compile error: a missing semicolon, an undeclared variable, or a header that cannot be found. Fix it, save, and the task succeeds, which makes the original message disappear.

Step 2: Build the File Manually to Double-Check

If the task output is confusing, remove VS Code from the equation. Open a terminal in your project folder and compile the exact file yourself:

g++ main.cpp -o main

If this also fails, the problem is in the code, and the terminal prints the same errors in a calmer format. If this succeeds, the code is fine and the task definition itself is wrong, which the next steps address. Also confirm the file you are editing is the file being built; debugging with a different file active in the editor is a surprisingly common trap.

Step 3: Check That the Task Label Matches launch.json

The link between the two files is a plain text label, and it must match exactly:

1. Open .vscode/launch.json and find the preLaunchTask value, for example "build".
2. Open .vscode/tasks.json and find the task’s label.
3. The two must be identical, including capital letters and spaces. "Build" and "build" are different labels.
4. If tasks.json does not exist or has no matching task, delete the preLaunchTask line temporarily to confirm the debugger then starts.

Many default C++ setups name the task something long, like C/C++: g++.exe build active file. If your launch file says just build while the task carries the long name, the task cannot be found or the wrong one runs. The launch.json reference for C++ debugging documents how these fields connect.

Step 4: Check the Task’s Compiler and File Arguments

Inside tasks.json, look at the command and args. Common faults include:

• The command names a compiler that is not installed or not on the PATH, such as g++ when only the Microsoft compiler exists.
• The args use ${file}, which means “the file currently active in the editor”. If you clicked into a header file or a text file before pressing F5, the compiler tries to build that instead, and fails.
• The output name in args after -o does not match the program path in launch.json, so the debugger looks for an executable that was never created.

A reliable pattern is to build with ${file} only for single-file learning projects, and to list your real source files, or point at a build system, for anything bigger.

Step 5: Make Sure the Program Is Not Still Running

On Windows especially, a task can fail because the previous copy of your program is still open, locking the executable file. The compiler then reports that it cannot write the output file, which surfaces as exit code 1. Close any running console window from an earlier debug session, check Task Manager for a stuck copy of your program, and try the build again.

Common Mistakes to Avoid

• Choosing “Debug Anyway” every time. That runs the old executable and hides real errors in your newest code.
• Fixing the last error in the list. Compiler errors cascade; fixing the first one often clears the rest.
• Having two tasks.json files. Only the one inside the .vscode folder of the opened workspace is used.
• Pressing F5 with the wrong file focused. Click into your main source file first so ${file} points where you expect.

When the Error Appears After Moving or Renaming the Project

A classic trigger for this error is moving your project folder, renaming it, or copying it from a tutorial. The files inside .vscode often contain paths and names from the original location or the tutorial author’s machine, so the build task points at a compiler or folder that no longer exists where it expects. If the error started right after a move, open both tasks.json and launch.json and scan for absolute paths, old folder names, or a previous user’s directory. For a small learning project, the cleanest cure is to delete the .vscode folder entirely and let VS Code generate fresh configuration files the next time you run the debugger, then reapply any custom settings you actually need.

Conclusion

The preLaunchTask error is a messenger, not the disease. It tells you the build before debugging failed, and the real reason is always visible in the task’s terminal output or the Problems panel. Read the first compiler error, fix the code, then verify that the task label matches launch.json exactly and that the compiler and output names line up. Once the build succeeds on its own, F5 will take you straight to your breakpoints.

Frequently Asked Questions

What does exit code 1 mean in a VS Code task?

It means the command inside the task finished with an error. For a build task, that is almost always a compiler error in your code or a missing compiler, and the task’s terminal output shows the exact message.

How do I see the full build output behind the error?

Run Terminal > Run Build Task and pick your build task. The terminal panel shows everything the compiler printed, starting with the first and most important error.

Can I debug without a preLaunchTask?

Yes. Remove the preLaunchTask line from launch.json and the debugger starts immediately, but it will run whatever executable already exists, which may be an old version of your program. Building first is safer.

Why does the task build the wrong file?

Because the task probably uses ${file}, which means whichever file is active in the editor. If a header or notes file is focused when you start, that is what gets compiled. Click your main source file first.

Where do I learn what each launch.json field means?

The official VS Code guide to using GCC with MinGW walks through working tasks.json and launch.json examples for C++, which you can compare line by line with your own files.