Start with the error shown in the app and the installed version. Check the relevant section below before changing several settings at once.
openscience --version
openscience doctor
Command not found or app will not open
Open a new terminal after installing. For a standalone CLI install, confirm that ~/.openscience/bin is on PATH. For npm, check that your npm global executable directory is on PATH.
Download the desktop build that matches your operating system and processor. If an older desktop download fails, try the current official release and read its platform notes. Avoid mixing files from different releases.
If Windows reports spawn /bin/ps ENOENT, the desktop build is running a macOS
updater check during startup. Track the fixed installer in
issue #543.
To keep working, install Node.js and run npx synsci in a terminal to open the
CLI's browser workspace, which uses a separate startup path.
No models available
Open Customize → Models and check the selected access mode.
- For Ace, sign in and verify the funding workspace and Wallet access.
- For Keys & subscriptions, reconnect the provider and check API or subscription access.
- For a local model, confirm that its server is running and the model is registered.
Use openscience models --flat for exact IDs. A key supplied to one provider does not enable a different provider's model.
A key works in a terminal but not the desktop app
The desktop app may not inherit environment variables exported in a shell. Save the key through Customize → Models, or launch the CLI from the shell where the variable is set.
If a removed key still appears active, check environment variables and shared workspace access as well as saved local credentials.
Ace is unavailable or uses the wrong balance
Check Customize → General → Funding workspace. A project name and an account workspace name can differ.
Complete workspace switching in the browser, return to the app, and use Sync now. If access was revoked, an administrator may need to restore membership or the shared connection.
A pending reservation can reduce available funds before the final charge appears. See Pricing. Changing model access to Keys & subscriptions does not disable automatic Wallet reloads.
A response is slow or times out
The running header shows Thinking or the active tool, with elapsed time. Hover over it for connection and provider details. A wait before the first response can include connection and service processing time.
Inference and Ace credential requests use fresh connections to avoid stale connection reuse in the bundled runtime. This prevents one source of long connection waits; it does not shorten a model's reasoning or an upstream queue.
Start with a short request and verify the selected model. For a self-hosted model, check server load, memory, context size, and whether it can complete a request directly.
Received output remains in the conversation after a timeout. Review completed tools and files before retrying, especially for a paid request. Configurable deadlines are described in Custom providers.
Local model discovery is empty
Check that the runtime is running, a model is downloaded or loaded, and you used the correct base URL.
curl http://localhost:11434/v1/models
openscience local list
For Ollama, start ollama serve if needed. For LM Studio, start its local server after loading a model. Rescan in Customize → Local models.
If a --bare request works but research tasks fail, verify tool calling and reduce the input or context size. See Local models.
Updating reports that OpenScience could not quit safely
Finish active sessions and compute jobs, then retry the verified update. The desktop waits for all project runtimes to release their processes before it exits; the reported error identifies a failed disposal. It does not force an update over active work. A completed setup stays complete after an update, even if the onboarding flow has changed. An explicit setup reset still opens onboarding.
Files are missing or the wrong copy opens
Confirm that you opened the intended project. In Files, check Project files and Session scratch separately. Read the location shown in the preview.
Local result links using file: or sandbox: open in Files. These prefixes do
not grant access to a folder: the server still checks the current session's
file permissions.
For protected folders on macOS, grant the folder access the operating system requests to the app or terminal you are using, then reopen the folder. A project path must exist and be accessible on the machine running OpenScience.
Use Files and storage for data locations and backups.
A scientific tool needs setup
Open Customize → Tools and Customize → Compute. Complete the relevant installation or connection action and test a small input.
A skill's presence does not mean its dependencies are installed. A saved service key does not mean your account has access to every model or resource. Preserve the reported error and job identifier instead of repeatedly starting the same job.
Python or R repair reports a Windows file lock
Update OpenScience, then retry Set up or repair in Customize → Compute. Repair rechecks both starters, and setup waits briefly for temporary Windows file locks to clear. A starter can show Ready while saving the setup status fails: the label reflects whether its interpreter runs.
If EPERM, EACCES, or EBUSY persists, finish running Python or R work, close other OpenScience instances, and reopen the app before retrying. Keep the existing data folder. Add the full error text, including both rename paths, your Windows and OpenScience versions, and whether Python or R execution also fails to issue #714.
A connector will not connect
In Customize → Connectors, check whether it is saved but off, awaiting authorization, or reporting an error.
For a local connection, verify the executable and dependencies. For a remote one, verify the HTTPS endpoint and finish authorization. See Connectors.
A terminal task exits immediately
Use the exit-code table. Code 2 usually means invalid arguments or missing configuration. Code 3 indicates a rejected permission or question; noninteractive runs reject prompts by default.
Provide the missing information and choose an appropriate run policy. Do not automatically enable all actions just to suppress an unexplained failure.
Report a reproducible problem
Use GitHub Issues for product bugs. Include the version, operating system, access mode, exact error, and the smallest steps or sample that reproduce it.
Remove API keys, private datasets, and unrelated conversation content. For account or payment details, use support through your billing account instead of a public issue. For a security vulnerability, follow the security reporting policy.