Troubleshooting

Errors explain themselves

Most failures arrive as a card in the transcript that says what went wrong in plain words, what to do next, and often offers a button that does it — Compact the conversation, Continue, Open Settings. The raw error is always one click away underneath.

So the first answer to "something went wrong" is usually: read the row. It was written for this.

Signing in

"Claude Code couldn't sign in" — the API key in Settings → Account is wrong, expired, or revoked. Create a fresh one in the Anthropic Console and paste it in.

It works in my terminal but not in Vitrino. Expected. Vitrino ignores ANTHROPIC_API_KEY and every other credential variable from your environment, on purpose — see First run. Put the key in Settings.

"A billing problem stopped this request" or "Your Anthropic account is on hold" — these come from Anthropic, not Vitrino. Check your plan, credits and key in the Console.

Limits

"You've reached a usage limit" — the chip below the message box says when it resets.

"The conversation is too long for the model" — compact it. The error card offers the button; so does the context meter's menu.

"Claude reached the turn limit" — it stopped, it did not fail. Ask it to continue.

Claude has forgotten everything

Look up the transcript for a marker:

• Conversation cleared — you ran /clear. Nothing above that line reaches Claude any more.
• History compacted — the earlier conversation was replaced by a summary. Claude has the gist, not the detail.

Both are drawn as full‑width markers so they are findable by scrolling back.

Nothing happens when I send

Check whether Claude is already working — a message sent mid‑turn is queued, not lost, and queued messages are listed above the box. Stop ends the turn and keeps the queue.

Linux: it will not start, or the sandbox complains

Install the .deb or .rpm rather than the AppImage. Their post‑install step configures Chromium's sandbox for your system — a setuid helper where unprivileged user namespaces are disabled, or an AppArmor profile on Ubuntu 24.04 and later.

Windows: SmartScreen blocks the installer

The installer is not code‑signed yet. Choose More info, then Run anyway. See Install.

macOS: "Vitrino is damaged and can't be opened"

Vitrino is signed and notarised, so this almost always means an incomplete download. Delete it and download again. Do not work around the warning — a genuinely damaged app is not one you want to run.

Reading the log

Settings → About links straight to the log folder. main.log holds what the main process recorded, including update checks and anything that failed quietly.

That is the right thing to attach if you report a problem.

Still stuck

Email support@vitrino.dev with what you were doing, what happened, the version from Settings → About, and the log if you have it.