{"record":{"id":"b03e983c016d2331","repo":"OpenRA/OpenRA","slug":"failed-to-initialize-an-opengl-debug-message-callb","errorCode":null,"errorMessage":"Failed to initialize an OpenGL debug message callback.","messagePattern":"Failed to initialize an OpenGL debug message callback\\.","errorType":"exception","errorClass":"InvalidProgramException","httpStatus":null,"severity":"critical","filePath":"OpenRA.Platforms.Default/OpenGL.cs","lineNumber":560,"sourceCode":"\t\t\t// Setup the debug message callback handler\n\t\t\tif (Features.HasFlag(GLFeatures.DebugMessagesCallback))\n\t\t\t{\n\t\t\t\ttry\n\t\t\t\t{\n\t\t\t\t\tvar suffix = Profile == GLProfile.Embedded ? \"KHR\" : \"\";\n\t\t\t\t\tglDebugMessageCallback = Bind<DebugMessageCallback>(\"glDebugMessageCallback\" + suffix);\n\t\t\t\t\tglDebugMessageInsert = Bind<DebugMessageInsert>(\"glDebugMessageInsert\" + suffix);\n\n\t\t\t\t\tglEnable(GL_DEBUG_OUTPUT);\n\t\t\t\t\tglEnable(GL_DEBUG_OUTPUT_SYNCHRONOUS);\n\n\t\t\t\t\t// Need to keep a reference to the callback so it doesn't get garbage collected\n\t\t\t\t\tDebugMessageHandle = DebugMessageHandler;\n\t\t\t\t\tglDebugMessageCallback(DebugMessageHandle, IntPtr.Zero);\n\t\t\t\t}\n\t\t\t\tcatch (Exception e)\n\t\t\t\t{\n\t\t\t\t\tthrow new InvalidProgramException(\"Failed to initialize an OpenGL debug message callback.\", e);\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tConsole.WriteLine(\"OpenGL renderer: \" + glGetString(GL_RENDERER));\n\t\t\tConsole.WriteLine(\"OpenGL version: \" + glGetString(GL_VERSION));\n\n\t\t\ttry\n\t\t\t{\n\t\t\t\tglFlush = Bind<Flush>(\"glFlush\");\n\t\t\t\tglViewport = Bind<Viewport>(\"glViewport\");\n\t\t\t\tglClear = Bind<Clear>(\"glClear\");\n\t\t\t\tglClearColor = Bind<ClearColor>(\"glClearColor\");\n\t\t\t\tglFinish = Bind<Finish>(\"glFinish\");\n\t\t\t\tglCreateProgram = Bind<CreateProgram>(\"glCreateProgram\");\n\t\t\t\tglUseProgram = Bind<UseProgram>(\"glUseProgram\");\n\t\t\t\tglGetProgramiv = Bind<GetProgramiv>(\"glGetProgramiv\");\n\t\t\t\tglCreateShader = Bind<CreateShader>(\"glCreateShader\");\n\t\t\t\tglShaderSource = Bind<ShaderSource>(\"glShaderSource\");","sourceCodeStart":542,"sourceCodeEnd":578,"githubUrl":"https://github.com/OpenRA/OpenRA/blob/a520984d91eda9de48a62b1d15c1e3bad0d4fb1a/OpenRA.Platforms.Default/OpenGL.cs#L542-L578","documentation":"Thrown when setting up the OpenGL debug-message callback fails: binding glDebugMessageCallback(+suffix), glDebugMessageInsert, enabling GL_DEBUG_OUTPUT / GL_DEBUG_OUTPUT_SYNCHRONOUS, or registering the callback raised an exception. InvalidProgramException wraps the inner exception. This is a best-effort feature (driver-bug workaround path) whose failure still aborts init.","triggerScenarios":"When the GL feature set includes DebugMessagesCallback, Initialize sets up the callback; if binding or callback registration throws, the catch rethrows. More common on certain drivers that advertise the extension but misbehave.","commonSituations":"Driver advertises KHR_debug / ARB_debug_output but the function pointers are broken; a driver bug when registering the synchronous callback; platform-specific GL loader quirk; the suffix (ARB/KHR) resolution picking the wrong entry point.","solutions":["Force-disable the debug callback via Game.Settings.Graphics.DisableGLDebugMessageCallback (the code path that trips this only runs when that flag is false).","Update GPU drivers to fix the broken debug-callback entry points.","If on Linux + AMD/Radeon, the code already auto-disables this; on other affected drivers, set the disable flag."],"exampleFix":"// before - debug callback enabled, throws on buggy driver\nGame.Settings.Graphics.DisableGLDebugMessageCallback = false;\n// after - opt out of the buggy debug-callback path\nGame.Settings.Graphics.DisableGLDebugMessageCallback = true;","handlingStrategy":"validation","validationCode":"// Opt out of the debug-callback path before OpenGL.Initialize runs\nGame.Settings.Graphics.DisableGLDebugMessageCallback = true;","typeGuard":null,"tryCatchPattern":"if (!Game.Settings.Graphics.DisableGLDebugMessageCallback)\n{\n    try { OpenGL.Initialize(); }\n    catch (InvalidProgramException ex) when (ex.Message.Contains(\"debug message callback\"))\n    {\n        Game.Settings.Graphics.DisableGLDebugMessageCallback = true;\n        OpenGL.Initialize(); // retry without the callback\n    }\n}","preventionTips":["Default DisableGLDebugMessageCallback on for known-buggy drivers.","Report the driver to auto-disable (as the code already does for Linux + AMD/Radeon).","Keep graphics.log so users can confirm the callback was the failing step."],"tags":["opengl","graphics","driver","debug-callback","config","gpu"],"backgroundTag":null,"analyzedSha":"a520984d91eda9de48a62b1d15c1e3bad0d4fb1a","analyzedAt":"2026-08-13T15:30:14.787Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}