When something does not work
This page is organised by what you are seeing, not by which part of the app it belongs to. If you have an error message with words in it, the other page is the one you want — What the error messages mean.
The DISPATCH button is greyed out
It stays dim until you have typed something and a provider is selected.
Look at the dropdowns under the dispatch box. If the provider one is empty, you have not connected an AI service yet. See Setting up for the first time.
Tasks keep failing
- Open TELEMETRY and filter by ERROR.
- Open one and read what it says — most errors name the cause.
- Try the ↻ retry button. A single failure is often the provider having a bad minute.
- If every task fails the same way, it is almost always the provider: a key that has stopped working, a model name that no longer exists, or an account out of credit. Your provider's own console is where the truth is — the dashboard links to it.
See Dispatching work.
An agent will not search the web
Two separate switches have to be on.
A search provider must be connected in System Config → Connections. Until then the card says the agent cannot search.
That particular agent must be allowed to search. It is a per-agent setting, chosen when you create one. The count at the foot of the agent list tells you how many have it; if it reads zero, that is your answer.
See Connections.
Voice does nothing
Work down in this order:
- Is a voice provider connected? Without one the voice features are disabled outright, not merely quiet.
- Is Voice Mode anything other than Off?
- Has your operating system given GNexusOS microphone permission? That is a system setting, not an app one.
- In conversational mode, did you click the orb to open the conversation?
- Is a meeting running? Meeting mode takes the microphone and will not share it.
See Voice.
Computer use will not start
Open System Config → Control and read the PERMISSIONS line under diagnostics. You need both accessibility and screen recording: one to act, one to see.
Grant them in System Settings → Privacy & Security, then fully relaunch the app. Closing the window is not a relaunch — quit it properly and open it again. This is the step most people miss.
If clicks are landing in the wrong place, run INPUT DISPATCH TEST on the same panel. It checks every display, including ones to the left of your main screen, which is the arrangement that most often goes wrong.
See Letting an agent use your computer.
My meeting transcript only has me in it
This is almost always screen recording permission.
Your computer removes sound it is playing from what your microphone hears, so that callers do not hear themselves echo. That same processing removes the other people from your recording. The only way to get them is for the app to capture the meeting application's audio directly, and that needs screen recording permission.
Two other causes:
The screen went to sleep or locked. Capture needs the display awake. Turn off your screen saver before a long call.
The app is not one it can tap. Only some meeting applications can have their audio captured; for the rest the dialog tells you upfront that it will hear your side only.
See Meeting mode.
A scheduled workflow did not run
The scheduler only runs while GNexusOS is open. The panel says so when you set the schedule.
If your machine was asleep or the app was closed at the appointed time, nothing happened and nothing is queued. For anything that genuinely must happen whether you are there or not, a scheduled workflow is the wrong tool.
See Workflows.
An approval disappeared before I answered it
Check whether the card carried the red label reading SESSION-SCOPED. Those belong to a task that is running, and they die when that run ends. They are not recoverable and the request simply did not happen.
Everything without that label waits in the queue indefinitely. Turn on SHOW RESOLVED to check whether you answered it and forgot.
See Approvals.
I cannot find an artifact an agent made
Check which project you are in. Artifacts belong to the context they were made in, and the workspace panel only lists the current one. The control at the top left switches context.
Check whether the task was purged. Purging a task moves its artifact to a
DeletedArtifacts/ folder rather than destroying it, so it is recoverable.
Open the folder yourself. OPEN IN FINDER on the workspace panel takes you there, and sometimes the file is sitting in plain sight under a name you did not expect.
The memory vault stopped syncing
Open System Config → Memory.
"Not found — sync is paused." The Obsidian vault folder is not where the app expects. An unplugged drive or a cloud folder that has not finished downloading will do this. Nothing has been deleted; reconnect and it resumes.
A count of files that could not sync. Those files were locked or permission was denied. Close whatever has them open and sync again.
Something under NEEDS YOUR ATTENTION. The same note changed in both places. Both versions were kept — one as the synced file, one beside it — and it waits for you to decide.
See Memory.
The app is slow, or files seem to be missing
Open System Config → Backup and choose RUN DIAGNOSTICS. It checks database integrity, the directory structure, permissions, orphaned artifacts and free disk space. It is read-only and safe at any time.
If it reports a problem you cannot fix, restore your most recent backup — a safety snapshot of the current state is taken automatically first, so the way back exists.
A system agent says it cannot reach my files
A system agent that shows ONBOARDING: PENDING has not finished setting up, and says:
COMPLETE ONBOARDING TO ACCESS FILES.
Finish its onboarding and it gains access. Until then it works, but not with your workspace.
See Governance and the constitution.
A provider looks configured but every task fails
If Settings shows a provider with a key saved, yet nothing using it works, the key file is probably there but unreadable.
Keys are stored encrypted in your workspace, and the secret that decrypts them is tied to this machine and to the app's own signature. Three things break that link:
- The workspace was copied from another computer.
- Your login keychain is locked.
- The app was replaced with a differently-signed build — swapping between a development build and a released one does it.
In every case the provider still looks configured, because the file exists. Re-enter the key in System Config → Providers and it will work again.
An option is there but nothing happens
One known case: the Call Completed workflow trigger. Some versions let you select it, but telephony is not switched on in shipped builds, so nothing can ever fire it. A workflow set this way sits there looking armed. Give it a different trigger, or run it by hand.
Still stuck
Note down three things before you ask: the version printed under the wordmark at the top of the window, the exact wording of anything on screen, and what you did immediately before. Those three answer most of the questions anyone would ask you.
Then write to [email protected].
