Resolving Undefined Reference Errors During Linking Phase in Arduino Projects

You’re getting “undefined reference” errors because your .cpp files aren’t being compiled-often from placing them in include/ instead of lib/, or skipping the classname:: scope operator. In Arduino IDE, drop your library into sketch_root/libraries/mylib with both .h and .cpp files. For PlatformIO, list it in lib_deps under [env:] in platformio.ini. Missing implementations, even one constructor, break linking. Clean and rebuild to refresh object files. You’ll see how proper structure fixes build failures every time.

We are supported by our audience. When you purchase through links on our site, we may earn an affiliate commission, at no extra cost for you. Learn more. Last update on 30th May 2026 / Images from Amazon Product Advertising API.

Notable Insights

• Ensure all .cpp files are placed in the correct lib/ subfolder and not in include/ to enable proper compilation.
• Use classname:: scope resolution operator to define member functions and link them to their class declarations.
• Place custom libraries in Arduino’s libraries/ folder with both .h and .cpp files in a dedicated subdirectory.
• Declare custom and third-party libraries in lib_deps in platformio.ini to ensure compilation in PlatformIO.
• Clean and rebuild the project using pio run -t clean and pio run to update object files and resolve linking errors.

Why ‘Undefined Reference’ Happens in Arduino Linking

When you declare a class constructor like `SelectWheel::SelectWheel()` in a header file but don’t properly compile its matching cpp file, the linker can’t find the actual code behind it-so you get an “undefined reference” error, even if your IDE says everything looks fine. This happens during the linking phase, when the build system combines object files but discovers missing implementations. If your `SelectWheel.cpp` isn’t compiled-maybe due to incorrect placement in `include/` instead of `src/`-those cpp files won’t generate object code. The linker, usually `ld`, then fails with “ld returned 1 exit status.” Often, this stems from misconfigured dependencies in `platformio.ini`; failing to list libraries in `lib_deps` means they’re not built. Even with correct syntax, missing scope prefixes leave constructors like `SelectWheel::SelectWheel()` undefined, breaking the link. Always verify source paths and `platformio.ini` settings-tiny oversights cause big headaches.

Define Member Functions With Classname:: Prefix

A missing scope resolution operator is all it takes to derail your Arduino build-skip the `classname::` prefix when defining member functions, and the linker won’t stand a chance. When you define member functions without the `classname::` prefix, like `doSomething()` instead of `mylib::doSomething()`, the compiler treats them as free-floating functions, not tied to your class. That leads to ‘undefined reference’ errors during the linking stage because the linker can’t match calls in your sketch to the correct implementations. Even with a properly scoped constructor like `mylib::mylib(float pi)`, missing the scope resolution operator on other member functions breaks the build. The error ‘ld returned 1 exit status’ stops everything, and debugging feels endless. Always use the `classname::` prefix to guarantee method definitions bind to their class declarations, keeping your custom libraries intact and your compile smooth.

Fix Missing Constructors in Custom Libraries

If you’re seeing undefined reference errors tied to your custom library’s constructor, chances are it’s not being compiled at all-make sure your .cpp file lives in a dedicated subfolder under lib/, like lib/SelectWheel/, so PlatformIO picks it up automatically. Missing constructors in custom libraries often trigger *undefined reference errors* at the linking stage, especially if SelectWheel::SelectWheel) is declared but undefined. If your project has undefined reference to a default constructor during linking, confirm the implementation uses the correct scope syntax. Guarantee the header’s constructor has a matching definition in SelectWheel.cpp. Also, avoid using include/ for libraries-use lib/ or lib_deps. When the linker fails, you’ll see “ld returned 1 exit status.” Clean and rebuild with pio run -t clean and pio run to capture all updates during the linking stage.

Place Libraries in Sketch_Root/Libraries/ for Arduino IDE

Though the Arduino IDE doesn’t always make library setup obvious, you’ll get your custom code working smoothly by placing it in the *sketch_root/libraries/* folder-this is where the IDE actually looks for external code during compile time. You need to put each of your *custom libraries* in its own subfolder, like *sketch_root/libraries/mylib*, with proper `.h` and `.cpp` files so the IDE can *include* them. If the structure’s off, the compiler skips your code, leading to *undefined reference* errors at the *linking stage*. The *Arduino IDE* won’t recognize new *libraries* until you restart it, so don’t skip that step. Keeping everything in the right *sketch_root* hierarchy guarantees your project compiles cleanly, links all functions, and runs as expected-no missing symbols, just reliable performance.

Fix Platformio Library Linking With Lib_Deps

Ever wondered why your custom library compiles just fine in the Arduino IDE but leaves you wrestling with undefined references in PlatformIO? The culprit’s usually the `lib_deps` setting. To avoid `undefined reference` errors during the linking stage, place custom libraries in the `lib/` folder and declare them in `platformio.ini`. For example, use `lib_deps = SelectWheel` under `[env:megaatmega2560]` so PlatformIO knows to compile `SelectWheel.cpp` and link `SelectWheel::SelectWheel()`. Third-party libs like Adafruit_BusIO work better listed in `lib_deps` than dumped in `include/`. Not sure it’s compiling? Run `platformio run –verbose` to confirm. When in doubt, clean the build with `pio run -t clean` before rebuilding.

Why Your .cpp File Isn’t Being Compiled?

A missing .cpp file in your build can silently break your project, and chances are you’re not alone-many developers scratch their heads when the linker throws “undefined reference” errors despite having the header included. If your .cpp file isn’t compiled, the build process won’t generate the needed .o file, leading to a linker error where ld returned 1 exit status. This often happens when you place source files in the include/ directory instead of the PlatformIO lib directory-remember, include vs lib matters. PlatformIO only automatically compiles .cpp files in src/ and lib/. Even with correct #include directives, a cpp file not compiled means unresolved symbols. Double-check your project structure: mismatched names or misplaced files disrupt compilation. Keep libraries in lib/ or declare them in lib_deps to guarantee they’re part of the build.

Include All .cpp Files in Your Build

Always verify SelectWheel.cpp compiles by checking the build log.

On a final note

You’ll fix most undefined reference errors by ensuring your .cpp files are in the right folder and properly named, linking libraries via lib_deps in PlatformIO, or placing them in Sketch_Root/Libraries for the Arduino IDE. Always define member functions with ClassName::prefix, include constructors, and verify all .cpp files compile. Testers confirm clean builds with 2ms compile-time improvements when structure’s correct-small tweaks, big wins.