Troubleshooting

Start with gr doctor

cd ~/code/my-project
gr doctor

gr doctor checks the project end to end and says what is wrong in plain words: the project’s folder, its map and whether the map is level with the files, the git hooks, your account, the connection to Graphide’s servers and the cloud project, and your agents’ setup. Some of what it reports is by design, such as a map that keeps working while the servers are down, and it says which findings apply to you.

gr doctor --fix    # run the fixes it can, then check again

It exits 0 when nothing needs attention, 1 when something does, and 2 when something is wrong, so a script can use it.

Signing in

“this machine is not signed in to a Graphide account with active access”: run gr login, then try again. On a machine without a browser, such as one you reach over ssh, gr login shows an address and a code to type in a browser anywhere; gr login --no-browser asks for that on purpose.

“you are signed in, but this account is pending approval or suspended”: your account is not active yet. Your dashboard says where it stands. In the app this is the Waiting for approval card.

The app does not open

What you see	What to do
gr app install warns there is no Vulkan driver	Install your GPU’s Vulkan driver (mesa-vulkan-drivers on Ubuntu). Without it the window cannot draw.
no_display	There is no desktop session here, as over ssh. Open Graphide from the desktop.
app_running from an install or update	Quit Graphide first, or use gr app update, which waits for the next restart.
It started misbehaving after an update	gr app rollback goes back to the version before.

Install lists every install error.

Agents or plugins say there is no sandbox

On Linux, Graphide’s sandbox is bwrap: install bubblewrap with your package manager. Without it, what Graphide would run in the sandbox, such as a plugin’s programs, is refused rather than run unconfined.

“the Graphide daemon is not answering”

The daemon is the background service that serves every project on your machine. It stops when you quit Graphide from the tray or with gr daemon stop --all. Start it again:

gr daemon start
gr daemon status    # what it is doing, and how much it is carrying

One daemon serves every window and project for your user. If something reports bind: address already in use, another copy is already running; use gr daemon status and gr daemon restart rather than ending processes by name.

A command times out after the network dropped

On older builds, a command could hang and then fail with a message naming http://localhost/... and timeout awaiting response headers after the network dropped. The localhost there is the daemon, not a website. Update Graphide; until then, gr daemon stop --all, then run the command again.

The map is not building

The map’s card in the app says what it is waiting for: your place in the queue, the servers being full, another build of the same project, or the internet. Map your first project explains each one. From a terminal:

gr status    # how far the build is
gr doctor    # what stands in its way

For a very large repository, leave out what you do not need mapped, such as vendored code, generated files or data; see Leave parts of a project out.

A plugin misbehaves

gr plugin status <name> says how it runs and its last errors, and gr plugin rollback <name> puts back the version you approved before. To rule plugins out entirely, start Graphide with GRAPHIDE_PLUGINS=0. See When a plugin misbehaves.

Report a bug

In the app, choose Report bug: the red button in the status bar, the Help menu, or the command palette (:report in the Vim window). Say what happened, and attach the screenshot of the window as it was if you like. From a terminal:

gr report

Either way, Graphide collects this machine’s recent logs, the daemon’s status, your projects’ map counts and your settings, with your accounts and email addresses taken out, and sends them. It shows the report’s id: quote it in #feedback on our Discord. When a report could not be sent, it says where the file is, so you can attach that instead. gr report --no-upload keeps the bundle on your machine so you can look at it and attach it yourself, and gr report --list shows the reports filed from this machine, by you and by your agents.

gr logs shows the same events on your own screen.