Recipe

Fix a build that won't compile

Use when: the build stops and prints lines of the form file:line:column: error: message, and no executable was made

Goal: a clean build, reached by fixing one real mistake at a time instead of chasing every message at once

Taught in Reading compiler errors · a later section extends this recipe with more cases

1. 1

   Ignore everything below it for now. Scroll up to the top of the output and find the first line whose severity is error:. Lines marked warning: or note: above it can wait.

   Example

   The build prints six errors after one missing semicolon. The first, in Clang's wording, is main.cpp:4:22: error: expected ';' at end of declaration. That's the only line you read in this step.

   Why: the compiler keeps going after a mistake, so one real error can trigger many follow-on errors that aren't real.

2. 2

   Check who is complaining by the shape of the message. A compile error reads file:line:column: error: message, with error: right after the location: the mistake is in that file's text. A link error names a symbol that's missing or defined twice (undefined reference to, Undefined symbols, LNK2019), often shows an object-file offset like (.text+0x10), and ends with ld returned 1 exit status or linker command failed. Don't go by whether a line number appears: in a -g build the GNU linker adds one, pointing at the line that uses the missing function.

   • it has file:line:column: error: — it's a compile error; carry on with Step 3.
   • it says undefined reference, Undefined symbols, LNK2019, ld returned 1 exit status or linker command failed — it's a link error; every file compiled, so this recipe's steps don't apply. Look for a function that was declared but never defined, or a file or library that wasn't included in the build.

   Why: the two kinds have different causes. Even when a link error mentions a line, that line is fine: what's missing is a definition somewhere else, or a file left out of the build.

3. 3

   Read the location left to right and open the file there. The column number, and the caret (^) under the source line, show the exact spot.

   Example

   main.cpp:5:31: error: 'totl' was not declared in this scope; did you mean 'total'? means file main.cpp, line 5, column 31. The caret sits under totl.

   ⚡ Shortcut

   If the caret points at the very start of a line, look at the end of the line above it too. A missing ; or } is often noticed only when the compiler reaches the next line.

   Why: the location is where the compiler first got confused, which is at or just after the real mistake.

4. 4

   Read the message as a sentence and make the smallest change that answers it. Use any "did you mean" suggestion only after checking it's what you meant.

   Example

   "'totl' was not declared ... did you mean 'total'?" There's a variable called total two lines up, and totl is a typo, so change totl to total.

   Why: one small fix is easy to check. Fixing several guesses at once hides which one made the difference.

5. 5

   Build again. If there are still errors, go back to Step 1 and start from the new first error. Don't reuse the old list.

   Example

   After adding the missing ;, the rebuild shows zero errors: the other five were all caused by that one semicolon.

   • Not yet: the first error is inside a template, with pages of required from here and candidate notes — covered in Reading template errors

   Why: the old list was produced by the old code. After a fix, many of its messages simply disappear.

6. 6

   When the build succeeds, read any warning: lines before running the program.

   Why: a warning is legal code that is probably wrong. It is often the logic or runtime error you'd otherwise meet later.