Troubleshooting

Fixes for common problems, grouped by where they show up.

Models and keys#

"No models" or an empty picker. You have no OpenRouter key and no enabled provider with a key. Add one under Settings, 01 · Models & Routing.

A provider's models do not load. Press Test on the provider. A 401 or 403 means the key is wrong for that base URL. A 404 usually means the base URL is missing /v1, or the model list is elsewhere, so set a Models URL. See Bring your own providers.

Chat fails with an insufficient balance error. Your provider account is out of credit. Top it up, or enable the agent fallback model in Settings so turns finish on a cheaper model.

The agent stops and says budget_exceeded. You reached the daily spend limit. Raise it in Intelligence, Treasury or the Models hub and continue. See Usage, caching and budgets.

The agent#

A verification run fails with "The system cannot find the path specified." Update to the latest build. Older versions mishandled commands that began with cd "folder" on Windows. Current builds run these correctly.

Verification runs the wrong toolchain. In a repository that mixes Rust and JavaScript, the verifier picks the toolchain of the package being edited. If it still chooses wrong, tell the agent the exact command and it will run that with verify.

It keeps changing approach. An oscillation guard interrupts after repeated reversals. Reply with the approach you want, or switch to Plan to settle it first.

Everything asks for approval. You are on Strict, or Balanced with shell commands. Pick Balanced and turn on auto-approve in the composer for long runs. See Approvals and safety.

I want the last turn undone. Use Checkpoint in the chat. You can also discard changes in the Git panel.

The editor and preview#

The preview is blank. Check that a dev server is running and its URL matches the one in .rescriptum/dev-server.json. Stopping and starting it from the agent refreshes the record.

A dev server seems to be left running. Close it from the terminal, or ask the agent to stop it. Its record in .rescriptum/dev-server.json includes the real listening process ID.

The terminal opens the wrong shell. Set RESCRIPTUM_SHELL. See Configuration.

Rescriptum Tab#

The Tab panel does not show Linked. The IDE must be running, and port 49281 must not be blocked by another program. Reload the extension on chrome://extensions.

ask_tab is not in the agent's tools. The connected extension does not report research support. Install the latest zip and reload it.

Pinning does not show source file and line. The page must be a development build of a React app. Production bundles omit that information.

The picker shortcut does nothing. Check for a conflict at chrome://extensions/shortcuts.

Install and updates#

SmartScreen blocks the installer. Builds are not code-signed yet. Choose More info, then Run anyway, after checking the SHA-256 on the download page.

The update check finds nothing. The IDE reads the release list from rescriptum.com. Check your connection, or download the installer directly.

Still stuck#

Open Settings, 05 · Diagnostics to run the health check and copy the runtime information. Include it, and the steps that led to the problem, when you ask for help.