diff --git a/include/SDL_video.h b/include/SDL_video.h
index 41c3e10b0..0c05a0937 100644
--- a/include/SDL_video.h
+++ b/include/SDL_video.h
@@ -893,6 +893,12 @@ extern DECLSPEC void SDLCALL SDL_GetWindowSize(SDL_Window * window, int *w,
  * initialized to 0, 0, 0, 0 (if a non-NULL pointer is provided), as if the
  * window in question was borderless.
  *
+ * Note: This function may fail on systems where the window has not yet been
+ * decorated by the display server (for example, immediately after calling
+ * SDL_CreateWindow). It is recommended that you wait at least until the
+ * window has been presented and composited, so that the window system has a
+ * chance to decorate the window and provide the border dimensions to SDL.
+ *
  * This function also returns -1 if getting the information is not supported.
  *
  * \param window the window to query the size values of the border