gcc/g++ "unrecognized command-line option"

The compiler does not understand a flag you passed. Most often the CI image ships an older compiler than the one that supports the flag - a too-new -std=, a GCC-only option passed to Clang, or vice versa.

What this error means

Compilation fails before producing objects, reporting an unrecognized option or an invalid -std= value. It compiles locally with a newer compiler but fails on the CI image’s older one.

g++ output

cc1plus: error: unrecognized command-line option '-std=c++23'; did you mean '-std=c++2a'?

Common causes

Compiler older than the flag

A standard or option added in a newer GCC/Clang is unknown to the older version on the runner image (e.g. -std=c++23 on GCC 9).

Compiler-specific flag passed to the other compiler

A GCC-only flag handed to Clang (or the reverse) is rejected. CI may default to a different compiler than your local setup.

How to fix it

Install and select a newer compiler

Add a compiler version that supports the flag and point the build at it.

Terminal

apt-get install -y g++-13
cmake -S . -B build -DCMAKE_CXX_COMPILER=g++-13

Lower the standard or guard the flag

Drop to a standard the image supports (e.g. -std=c++20).
Gate compiler-specific flags on the compiler id in CMake (if(CMAKE_CXX_COMPILER_ID STREQUAL "GNU")).
Assert g++ --version early so the toolchain is explicit.

How to prevent it

Pin a compiler version in CI that supports your requested standard.
Use target_compile_features/CMAKE_CXX_STANDARD instead of raw -std= where possible.
Guard compiler-specific flags behind a compiler-id check.