diff --git a/cogl/cogl-sdl.h b/cogl/cogl-sdl.h
index 486732e92..2c3d60317 100644
--- a/cogl/cogl-sdl.h
+++ b/cogl/cogl-sdl.h
@@ -21,13 +21,26 @@
  *
  */
 
-#if !defined(__COGL_H_INSIDE__) && !defined(COGL_COMPILATION)
-#error "Only <cogl/cogl.h> can be included directly."
-#endif
-
 #ifndef __COGL_SDL_H__
 #define __COGL_SDL_H__
 
+/* NB: this is a top-level header that can be included directly but we
+ * want to be careful not to define __COGL_H_INSIDE__ when this is
+ * included internally while building Cogl itself since
+ * __COGL_H_INSIDE__ is used in headers to guard public vs private api
+ * definitions
+ */
+#ifndef COGL_COMPILATION
+
+/* Note: When building Cogl .gir we explicitly define
+ * __COGL_H_INSIDE__ */
+#ifndef __COGL_H_INSIDE__
+#define __COGL_H_INSIDE__
+#define __COGL_SDL_H_MUST_UNDEF_COGL_H_INSIDE__
+#endif
+
+#endif /* COGL_COMPILATION */
+
 #include <cogl/cogl-context.h>
 #include <cogl/cogl-onscreen.h>
 #include <SDL.h>
@@ -221,4 +234,17 @@ cogl_sdl_onscreen_get_window (CoglOnscreen *onscreen);
 
 COGL_END_DECLS
 
+/* The gobject introspection scanner seems to parse public headers in
+ * isolation which means we need to be extra careful about how we
+ * define and undefine __COGL_H_INSIDE__ used to detect when internal
+ * headers are incorrectly included by developers. In the gobject
+ * introspection case we have to manually define __COGL_H_INSIDE__ as
+ * a commandline argument for the scanner which means we must be
+ * careful not to undefine it in a header...
+ */
+#ifdef __COGL_SDL_H_MUST_UNDEF_COGL_H_INSIDE__
+#undef __COGL_H_INSIDE__
+#undef __COGL_SDL_H_MUST_UNDEF_COGL_H_INSIDE__
+#endif
+
 #endif /* __COGL_SDL_H__ */
diff --git a/cogl/cogl.h b/cogl/cogl.h
index 5035a99d8..9d7c03ed7 100644
--- a/cogl/cogl.h
+++ b/cogl/cogl.h
@@ -138,9 +138,6 @@
  * code has been migrated down into Cogl! */
 #include <cogl/deprecated/cogl-clutter.h>
 #endif
-#ifdef COGL_HAS_SDL_SUPPORT
-#include <cogl/cogl-sdl.h>
-#endif
 
 /*
  * API deprecations
diff --git a/examples/cogl-sdl-hello.c b/examples/cogl-sdl-hello.c
index 3d656e3dd..157c3e8e2 100644
--- a/examples/cogl-sdl-hello.c
+++ b/examples/cogl-sdl-hello.c
@@ -1,4 +1,5 @@
 #include <cogl/cogl.h>
+#include <cogl/cogl-sdl.h>
 #include <stdio.h>
 #include <SDL.h>
 
diff --git a/examples/cogl-sdl2-hello.c b/examples/cogl-sdl2-hello.c
index f84c40e1e..0e32fdbe4 100644
--- a/examples/cogl-sdl2-hello.c
+++ b/examples/cogl-sdl2-hello.c
@@ -1,4 +1,5 @@
 #include <cogl/cogl.h>
+#include <cogl/cogl-sdl.h>
 #include <stdio.h>
 #include <SDL.h>