Skip to content

Commit d60647b

Browse files
mitchellhmitchellh
committed
Help page for OpenGL context issues
1 parent 28bb903 commit d60647b

File tree

3 files changed

+101
-13
lines changed

3 files changed

+101
-13
lines changed

‎docs/help/gtk-opengl-context.mdx‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
---
2+
title: GTK OpenGL Context Errors
3+
description: |-
4+
In some situations, Ghostty may fail to start with an error about being
5+
"unable to acquire an OpenGL context". This page adds more details about
6+
this error and how to resolve it.
7+
---
8+
9+
The Ghostty GTK application uses OpenGL for rendering. To render with
10+
OpenGL, Ghostty needs to first acquire an "OpenGL context" from GTK. This
11+
gives us the namespace to execute OpenGL commands.
12+
13+
In rare situations, GTK may be unable to provide Ghostty with an OpenGL
14+
context. When this happens, Ghostty is unable to render anything and must
15+
show this error.
16+
17+
This is **always an environment issue**. GTK provides Ghostty with the OpenGL
18+
context, and there isn't generaly anything Ghostty itself can do to resolve
19+
this directly. It is usually an issue regarding a library, driver, or OS
20+
package version. This page will attempt to provide some assistance in
21+
tracking down the issue.
22+
23+
## Quick Fixes
24+
25+
If you want to try to get Ghostty working quickly, try the following.
26+
27+
1. **Install a [binary package](/docs/install/binary).** If you're building
28+
from source, try using a binary package instead. Binary packages tend
29+
to be built in a more controlled environment that works with a specific
30+
distribution and its libraries.
31+
32+
2. **Check your GPU drivers.** GPU drivers are a common cause of OpenGL
33+
issues. Try updating or downgrading your GPU drivers, especially if
34+
you're using proprietary drivers.
35+
36+
3. **Build Ghostty from source using only system packages.** If you're using
37+
the Nix development environment to build Ghostty, try building it
38+
from source using only system packages. See the
39+
[build from source](/docs/install/build) instructions to do this
40+
(but ignore the "Building with Nix" section).
41+
42+
<Important>
43+
This section purposely avoids any detail in understanding the root cause of
44+
this issue. If you want to better understand the root cause, please read below
45+
this section.
46+
</Important>
47+
48+
## Mismatched Library Versions
49+
50+
A common cause of this error is mismatched library versions. The balance
51+
between GTK, [Mesa](https://mesa3d.org/), libX11/libwayland, and the kernel is
52+
a fragile one.
53+
54+
**The first most common cause of this error is using the Nix development
55+
environment to build Ghostty.** We recommend this environment for development,
56+
but it does pin various versions of these libraries and they may be
57+
incompatible with your global system. **To fix: try to build Ghostty using
58+
only system dependency packages, or Ghostty itself from a system package.**
59+
You can follow the [build from source](/docs/install/build) instructions
60+
to do this (but ignore the "Building with Nix" section)
61+
62+
**Another common cause is outdated system packages.**
63+
Linux distributions tend to handle this fragile balance for you, so the
64+
try to update your entire system (or, specifically the
65+
packages above, at least). This often brings your system back into a
66+
coherent state that allows Ghostty to work.
67+
68+
**Check your GPU drivers.** Try updating or downgrading your GPU drivers.
69+
We've had many cases where GPU driver changes have broken OpenGL in GTK.
70+
71+
## Known Historical Causes
72+
73+
- [Mesa 25.2.0 Regression](https://gitlab.freedesktop.org/mesa/mesa/-/issues/13719).
74+
Ghostty doesn't bundle a libwayland clent library, but building Ghostty
75+
from source with the Nix development environment will use a different
76+
libwayland client library than the system one.
77+
78+
- [GTK4 + Nvidia + X11](https://gitlab.gnome.org/GNOME/gtk/-/issues/4950).
79+
I don't know the exact combination required to trigger this, but it seems
80+
in certain scenarios, the mixture of GTK4 (required by Ghostty), Nvidia,
81+
and X11 can cause this issue. Changing driver versions or changing to
82+
Wayland can resolve this.

‎docs/help/index.mdx‎

Lines changed: 14 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -12,21 +12,22 @@ we try to document as many common issues and solutions as possible.
1212

1313
## Common Issues and Solutions
1414

15-
| Issue | Solution |
16-
|-------|----------|
17-
| Error "missing or unsuitable terminal" when running commands or using SSH. | [Terminfo](/docs/help/terminfo) |
18-
| macOS window managers such as Yabai or Aerospace act strange | [macOS Tiling Window Managers](/docs/help/macos-tiling-wms) |
19-
| Ghostty has slow startup or high memory usage on Linux. | [GTK Single Instance](/docs/help/gtk-single-instance) |
20-
| macOS defaults to login shells | [macOS Login Shells](/docs/help/macos-login-shells)
15+
| Issue | Solution |
16+
| -------------------------------------------------------------------------- | ----------------------------------------------------------- |
17+
| Error "missing or unsuitable terminal" when running commands or using SSH. | [Terminfo](/docs/help/terminfo) |
18+
| macOS window managers such as Yabai or Aerospace act strange | [macOS Tiling Window Managers](/docs/help/macos-tiling-wms) |
19+
| Ghostty has slow startup or high memory usage on Linux. | [GTK Single Instance](/docs/help/gtk-single-instance) |
20+
| "Unable to acquire OpenGL context" error on Linux | [GTK OpenGL Context](/docs/help/gtk-opengl-context) |
21+
| macOS defaults to login shells | [macOS Login Shells](/docs/help/macos-login-shells) |
2122

2223
## Seeking Help
2324

2425
If the common issues and solutions above did not help and you
2526
can't find an answer in the documentation, the following resources
2627
are available:
2728

28-
<CardLinks cards={
29-
[
29+
<CardLinks
30+
cards={[
3031
{
3132
title: "GitHub Discussions",
3233
description: "Search for and ask questions from the community on GitHub.",
@@ -36,7 +37,7 @@ are available:
3637
title: "Discord",
3738
description: "Real-time chat with the community. Community-moderated.",
3839
href: "https://discord.gg/ghostty",
39-
}
40+
},
4041
]}
4142
/>
4243

@@ -45,8 +46,8 @@ are available:
4546
Please, please, please read the [contributing guide on GitHub](https://github.com/ghostty-org/ghostty/blob/main/CONTRIBUTING.md).
4647

4748
<Important>
48-
**GitHub Issues is probably not the right place to go.** This project
49-
starts all bugs and feature requests as discussions on GitHub Discussions
50-
until more specific details are known. From there, we convert them into
51-
GitHub Issues as needed. See the contributing guide for more details.
49+
**GitHub Issues is probably not the right place to go.** This project starts
50+
all bugs and feature requests as discussions on GitHub Discussions until more
51+
specific details are known. From there, we convert them into GitHub Issues as
52+
needed. See the contributing guide for more details.
5253
</Important>

‎docs/nav.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -420,6 +420,11 @@
420420
"path": "/gtk-single-instance",
421421
"title": "GTK Single Instance"
422422
},
423+
{
424+
"type": "link",
425+
"path": "/gtk-opengl-context",
426+
"title": "GTK OpenGL Context"
427+
},
423428
{
424429
"type": "link",
425430
"path": "/macos-tiling-wms",

0 commit comments

Comments
 (0)