diff --git a/sys/include/riotboot/flashwrite.h b/sys/include/riotboot/flashwrite.h
index eac6cc793c..2591b375c6 100644
--- a/sys/include/riotboot/flashwrite.h
+++ b/sys/include/riotboot/flashwrite.h
@@ -59,6 +59,9 @@ extern "C" {
 
 /**
  * @brief   firmware update state structure
+ *
+ * @note    @ref FLASHPAGE_SIZE can be very large on some platforms, don't place
+ *          this struct on the stack or increase the thread stack size accordingly.
  */
 typedef struct {
     int target_slot;                        /**< update targets this slot     */