diff --git a/platformio.ini b/platformio.ini
index 63174c08..10b72ebe 100644
--- a/platformio.ini
+++ b/platformio.ini
@@ -13,7 +13,10 @@ framework = arduino
 monitor_speed = 115200
 upload_speed = 921600
 check_tool = cppcheck
-check_flags = --enable=all --suppress=missingIncludeSystem --suppress=unusedFunction --suppress=unmatchedSuppression --suppress=*:*/.pio/* --inline-suppr
+; missingInclude (project headers) is suppressed alongside missingIncludeSystem: on a
+; fresh CI checkout cppcheck has no resolved include paths, so it reports every
+; project header as missing (~400 information-level lines) and fails the job.
+check_flags = --enable=all --suppress=missingIncludeSystem --suppress=missingInclude --suppress=unusedFunction --suppress=unmatchedSuppression --suppress=*:*/.pio/* --inline-suppr
 check_skip_packages = yes
 
 board_upload.flash_size = 16MB