diff -r 57cc5fc047f3 -r 35e098a663a7 ui/cocoa/toolkit.m
--- a/ui/cocoa/toolkit.m	Thu May 28 17:45:20 2026 +0200
+++ b/ui/cocoa/toolkit.m	Thu May 28 18:07:00 2026 +0200
@@ -50,13 +50,34 @@
 static int app_argc;
 static const char **app_argv;
 
-static UiBool        exit_on_shutdown;
+static UiBool exit_on_shutdown;
+
+static char *main_thread_error_msg;
+
+// This function is only used by language bindings, to improve error messages
+// for example, when using java bindings, this can provide infos how to fix
+// this (-XstartOnFirstThread)
+void ui_set_main_thread_error_msg(const char *msg) {
+    main_thread_error_msg = msg ? strdup(msg) : NULL;
+}
 
 /* ------------------- App Init / Event Loop functions ------------------- */
 
 static AppDelegate *app_delegate;
 
+static void main_thr_check(const char *func) {
+    if(![NSThread isMainThread]) {
+        fprintf(stderr, "Error: %s must run on the main thread.\n", func);
+        if(main_thread_error_msg) {
+            fprintf(stderr, "%s\n", main_thread_error_msg);
+        }
+        exit(1);
+    }
+}
+
 void ui_init(const char *appname, int argc, char **argv) {
+    main_thr_check("ui_init");
+    
     application_name = appname ? strdup(appname) : NULL;
     app_argc = argc;
     app_argv = (const char**)argv;
@@ -124,6 +145,8 @@
 }
 
 void ui_main(void) {
+    main_thr_check("ui_main");
+    
     NSApplicationMain(app_argc, app_argv);
     //[NSApp finishLaunching];
     //[NSApp activateIgnoringOtherApps:YES];