assert in C++: how assert and static_assert work

assert in C++ is a macro from <cassert> that checks a condition while the program runs: assert(level <= 10); does nothing when the condition is true, and when it is false prints the condition, the file and the line, then stops the program. Defining NDEBUG, as release builds usually do, removes every assert. static_assert checks at compile time instead.

A volume control that accepts 0 to 10, as a whole program:

#include <cassert>
#include <iostream>

void set_volume(int level) {
    assert(level >= 0 && level <= 10);
    std::cout << "volume set to " << level << '\n';
}

int main() {
    set_volume(7);  // prints "volume set to 7"
}

It printed volume set to 7: the condition was true, so the assert did nothing.

The samples are C++17 (the one on contracts C++26), built with MSVC 19.44, Clang 19.1 (MSVC STL), GCC 16.2 and Clang 23.1 (libc++). Apart from contracts, all four behaved the same; only the wording of a failure differs. The samples whose assert fails were built as volume.cpp, the file name their messages show. Since When lists, for each standard, the first compiler releases that support its features.

What does a failed assert look like?

A failed assert writes one line to standard error, the output meant for error messages, naming the condition, the file and the line. Then it calls std::abort, which ends the program at once. Call the function above with 11 instead, set_volume(11);, and GCC 16.2 and Clang 23.1, both on Linux, printed:

output.s: volume.cpp:5: void set_volume(int): Assertion `level >= 0 && level <= 10' failed.

The line starts with the program’s name, here output.s. volume set to 11 never appeared: the program stopped at the assert. On Windows, MSVC and Clang 19.1 (both on Microsoft’s runtime library) print the condition, the file and the line, without the function name: Assertion failed: level >= 0 && level <= 10, file volume.cpp, line 5. Linked with Microsoft’s debug runtime library, a failed assert opens a dialog box with Abort, Retry and Ignore buttons; Retry opens the debugger (Microsoft’s assert page).

How do you add a message to an assert?

Join a string literal to the condition with &&. A string literal counts as true, so the check is unchanged, and the text shows up in the failure message:

void set_volume(int level) {
    assert(level <= 10 && "volume goes from 0 to 10");
    std::cout << "volume set to " << level << '\n';
}

Called with 11, MSVC printed Assertion failed: level <= 10 && "volume goes from 0 to 10", file volume.cpp, line 5. All four printed the text, quotes included, and none warned about the &&. assert takes no message argument of its own, so this is the portable way to add one.

How do you disable assert in C++ (NDEBUG)?

Define the macro NDEBUG before <cassert> is included. Every assert after it becomes ((void)0), an expression that does nothing, and its condition is never evaluated:

#define NDEBUG  // before <cassert>: every assert below is removed
#include <cassert>
#include <iostream>

void set_volume(int level) {
    assert(level >= 0 && level <= 10);  // gone: nothing is checked
    std::cout << "volume set to " << level << '\n';
}

int main() {
    set_volume(11);  // prints "volume set to 11"
}

It printed volume set to 11 on all four.

You rarely write the #define yourself. The build passes NDEBUG on the compiler’s command line instead: -DNDEBUG for GCC and Clang, /DNDEBUG for MSVC. CMake adds it in its Release, RelWithDebInfo and MinSizeRel configurations, as its default flags for GCC and for MSVC show; its Debug configuration leaves NDEBUG out. That is why an assert that fired while you tested seems to stop working in a Release build: it is no longer there.

Because the whole assert(...) disappears, condition included, never put work the program needs inside one:

int main() {
    int attempts = 0;
    assert(++attempts > 0);  // wrong: the counting is inside the assert
    std::cout << "attempts: " << attempts << '\n';
}

Built as it stands, it printed attempts: 1. Built with -DNDEBUG (/DNDEBUG on MSVC), the same code printed attempts: 0, and no compiler warned. Do the work on its own line, ++attempts;, and assert on the result: assert(attempts > 0);.

When should you not use assert?

Do not use it for what can go wrong in a correct program, such as a missing file or a number the user typed. Check those with an if or an exception, caught with try and catch, because the check must still be there in a release build.

An assert is for a mistake in the code: a condition that cannot be false if the program is written correctly. If only your own code calls set_volume, a level of 11 is a bug and the assert is right; if the level comes from a keypress, 11 is input to reject with an if.

What is static_assert in C++?

static_assert is a check the compiler makes while it builds the program: the condition must be something the compiler can work out, such as a size, and when it is false the build stops with your message. It costs nothing when the program runs, NDEBUG does not remove it, and it needs no header. Since C++17 the message is optional (static_assert on cppreference):

constexpr int max_volume = 10;

static_assert(sizeof(int) >= 4,
              "this code needs an int of at least 32 bits");
static_assert(max_volume > 0);  // no message: allowed since C++17

Both checks passed on all four, where int has 4 bytes. When the condition is false, there is no program to run:

static_assert(sizeof(int) == 8, "this code needs a 64-bit int");

GCC stopped the build with your text in its error:

error: static assertion failed: this code needs a 64-bit int

All four put the text in their error. Because the check happens while the program is built, a static_assert cannot test a value known only when it runs, such as level: that is assert’s job.

What do contracts change in C++26?

C++26 adds contract assertions: contract_assert(condition); checks a condition inside a function, as assert does, and pre and post attach conditions to a function’s declaration. Of the four compilers here, only GCC 16.2 built it, with -std=c++26 and -lstdc++exp added to link the program; Clang 23.1 and MSVC 19.44 do not have it yet:

void set_volume(int level) {
    contract_assert(level <= 10);  // C++26: a contract assertion
    std::cout << "volume set to " << level << '\n';
}

Called with 11, the program GCC built stopped with a contract violation message naming the function, the file and the line.

assert, static_assert, exception or if?

Pick by what you are checking and when the check has to run:

The Language section has the other answers on the core language.