Skip to main content

Troubleshooting

The hotkey does nothing​

Another application may already own Alt+Shift+D. Change Celeris's hotkey in Settings, or quit the app holding it. On macOS, also confirm Celeris is still listed under System Settings → Privacy & Security → Accessibility.

The capture is blank or shows the wallpaper​

macOS has not granted Screen Recording. Add Celeris under System Settings → Privacy & Security → Screen Recording and restart the app. The grant only takes effect on relaunch.

If the grant disappears after an update, you are probably running a locally built, unsigned copy. Each rebuild gets a new signature, and macOS treats it as a new app. A signed release build keeps the grant across updates.

Celeris does not know which window I meant​

Celeris reads the frontmost app name and window title through Accessibility. Grant it under System Settings → Privacy & Security → Accessibility, or say which window you mean in the prompt.

Sign-in never completes​

Sign-in shows a pairing code, opens your browser at the Celeris Console a couple of seconds later, and waits for you to type that code there. If it stalls:

  • Check that the code you typed matches the one in Celeris. Use the copy button beside it rather than retyping.
  • Make sure the browser window did not open behind another app.
  • Start again from Settings → Account. The pending request expires after a few minutes.

Everything asks for approval​

That is the default for anything that changes state. Use Always allow on the calls you approve repeatedly to build up your allowlist, or turn on auto-run in Settings → Safety. Destructive operations always ask either way.

A command failed with "command not found"​

Celeris runs commands with the environment it inherits at launch. A tool installed into a shell-specific profile may be invisible when Celeris starts from the Dock or the Start menu. Either use an absolute path in the prompt, or relaunch Celeris from a terminal that has the tool on its PATH.

The conversation could not be compacted​

When a conversation grows past what fits in the model's context, Celeris compacts it: it summarizes the older part and saves the full text to spill files on your machine. If compaction fails after its retries, the composer shows an error ending in "Start a new chat with the saved spill paths".

The error's last line names the cause. If it says CELERIS_BASE_URL / CELERIS_API_KEY not configured, Celeris has no Celeris endpoint to send the compaction to: sign in from Settings → Account, or set CELERIS_BASE_URL and CELERIS_API_KEY in the environment Celeris starts from, then relaunch. Either way, start a new chat and point Celeris at the saved spill paths so the conversation continues where it left off.

A setting could not be saved​

When a change in Settings fails to stick, the page shows "Couldn't save; check your connection". The change is not lost from the field — it simply was not written. Check, in order:

  • The file on disk. Settings are stored in a local settings.json, and the save is a write to that file. If it is unreadable or the disk is full, the write fails. If Celeris could not read the file, it says so at the top of the page and will not save until it can be read again; fix the file's permissions (or move it aside) and try the change again.
  • The account. With settings sync on, a saved change is also pushed to your account. That push is best effort and never fails the save, but if the change does not appear on your other devices, reconnect from Settings → Account and edit the setting again.

A connector stopped working​

Tokens expire, and access can be revoked at the provider. Open Settings → Tools → Connectors, disconnect the connector, and connect again. Celeris sends you back through the provider's own consent page.

Voice does not hear me​

Check the microphone permission for Celeris in your operating system's settings, and confirm a speech provider key is set in Settings → Voice. Dictation also switches itself off after a minute of silence, so click the microphone again to resume.

Still stuck​

Type report a bug in the composer, or use the account menu ▸ Send feedback. The form arrives prefilled with a picture of the Celeris window and the recent activity in the session you are on, so the report usually needs nothing from you but a sentence. You can see and untick every attachment before you send it. Failing that, contact Celeris support with the approximate time of the run. Your session log holds exactly what happened.