Wednesday, October 1, 2025

Why C/C++ circular dependency causes "syntax error"

I have a headerA with methodA that uses a structB from headerB and therefore includes headerB. When I call methodA, I get a "syntax error" in headerA where methodA uses structB location. Details:
// headerB.h
#ifndef HEADER_B_H
#define HEADER_B_H
struct structB { int x; };
#endif

// headerA.h
#ifndef HEADER_A_H
#define HEADER_A_H
#include "headerB.h"
void methodA(structB param);
#endif

// main.cpp
#include "headerB.h" // headerB processed first
#include "headerA.h" // headerB already included, so HEADER_B_H is defined
                     // #include "headerB.h" does NOTHING
                     // structB is unknown! → SYNTAX ERROR
The "syntax error" occurs because the compiler doesn't know what structB is when it tries to compile methodA. If headerB includes headerA (directly or indirectly), you have a circular dependency. The C++ preprocessor just does text substitution - it doesn't understand C++ syntax. It can't detect circular dependencies because include guards prevent infinite loops, so the circular dependency becomes an incomplete type error instead.