STM32 "undefined reference to HAL_..." link error in CI

The compiler saw the HAL function prototype from a header, but the matching HAL source file was never compiled into the build, so the linker has no definition to bind the call to.

What this error means

A make link step fails with "undefined reference to `HAL_GPIO_Init'" (or another HAL symbol) after the objects compile successfully.

build/main.o: in function `main':
main.c:(.text+0x2a): undefined reference to `HAL_GPIO_Init'
collect2: error: ld returned 1 exit status
make: *** [Makefile:140: build/firmware.elf] Error 1

Common causes

The HAL source file is not in the build

The header is on the include path, but the corresponding stm32xx_hal_*.c was not added to the source list, so the symbol is undefined.

The HAL module is not enabled

The HAL config header has the module commented out, so its source compiles to nothing and the function is never defined.

How to fix it

Add the HAL source to the build

1. Add the matching stm32xx_hal_<module>.c to the Makefile sources.
2. Confirm its include path is present.
3. Re-link to resolve the symbol.

C_SOURCES += Drivers/STM32F4xx_HAL_Driver/Src/stm32f4xx_hal_gpio.c

Enable the HAL module

Uncomment the module in the HAL config header so its source is compiled.

#define HAL_GPIO_MODULE_ENABLED

How to prevent it

• Add every used HAL module's .c to the source list.
• Enable the corresponding module in the HAL config header.
• Keep the source list in sync with the HAL modules you call.

Related guides