Troubleshooting
Installing and opening
Section titled “Installing and opening”macOS says the app “can’t be opened” or “is damaged”
Section titled “macOS says the app “can’t be opened” or “is damaged””The current build isn’t notarized by Apple. Right-click Olyvr Workspace in Applications and choose Open, or use Open Anyway in System Settings → Privacy & Security. If macOS still says the app is damaged, remove the download quarantine flag and try again:
xattr -dr com.apple.quarantine "/Applications/Olyvr Workspace.app"Only do this for a file you downloaded from the official download page and whose checksum you verified.
Windows shows “Windows protected your PC”
Section titled “Windows shows “Windows protected your PC””The installer isn’t code signed yet. Click More info, then Run anyway.
The Linux AppImage won’t start
Section titled “The Linux AppImage won’t start”Make sure it’s executable (chmod +x). If you see a FUSE error, install libfuse2. If it reports a glibc version error, your distribution is older than the build machine; try a newer distribution.
macOS Accessibility permission
Section titled “macOS Accessibility permission”Olyvr’s bundle ID changed from earlier builds, so macOS treats it as a new app. If you granted Accessibility before, grant it again in System Settings → Privacy & Security → Accessibility.
Starting up
Section titled “Starting up”“Could not start Olyvr Workspace”
Section titled ““Could not start Olyvr Workspace””| Detail | Fix |
|---|---|
| Backend exited before readiness | Usually another copy of Olyvr is already running, or ports 9420–9429 are all in use. Quit other copies (check Activity Monitor or Task Manager) and try again. |
| Backend did not become ready within 30 seconds | The machine is busy or antivirus is scanning the app. Try again; on Windows, allow Olyvr in your antivirus. |
| Bundled backend missing | The installation is incomplete. Reinstall Olyvr. |
“Olyvr Workspace backend stopped”
Section titled ““Olyvr Workspace backend stopped””The engine exited while the app was open. Reopen Olyvr: chats and files are saved, and any run in progress is marked as interrupted. Nothing is retried automatically.
Models
Section titled “Models”“Configure a model endpoint…”
Section titled ““Configure a model endpoint…””No model is connected. Follow Choosing a model.
Answers fail with an HTTP error
Section titled “Answers fail with an HTTP error”See the troubleshooting tables in Custom endpoint and Subscription. Make sure the model supports streaming and tool calls.
“The run reached its 16-step limit”
Section titled ““The run reached its 16-step limit””The question needed more searching than one run allows. Ask the agent to continue, or ask a narrower question.
Workspace
Section titled “Workspace”“No readable text found; scanned documents require OCR”
Section titled ““No readable text found; scanned documents require OCR””The PDF is a scanned image. Run it through an OCR tool first, then import the result.
“Password-protected PDFs must be unlocked before import”
Section titled ““Password-protected PDFs must be unlocked before import””Remove the password in your PDF viewer and import again.
Account sign-in says “Configure the account provider before signing in”
Section titled “Account sign-in says “Configure the account provider before signing in””Your build has no sign-in client for that provider. See Builds without a sign-in client.
Documents
Section titled “Documents”“Artifact changed; reload before saving”
Section titled ““Artifact changed; reload before saving””The draft changed since you opened it, for example through an agent edit. Reload the panel and apply your changes again.
Still stuck?
Section titled “Still stuck?”Use Feedback in the app to export a report, and include what you were doing and the exact message you saw.