Troubleshooting

When something isn't working, ask Klaudius in Conversations: describe what you saw, or paste the message. It reads the error, works out what happened, and usually fixes it on the spot. If a run stopped, open it from Runs or Conversations: its last lines say why.

If your Settings → Health check card has a Run check button, it checks your folder, tools, credentials and every connection, and tells you what needs fixing. Run it after a big change, such as a new computer or a replaced credential.

A run stopped, or paused

A pool started with Run Klaudius stops itself in some cases and only pauses in others. Its entry under Running now says which.

What happened	What Klaudius does	What to do
Three runs in a row failed	Stops, so it doesn't keep failing	Open the last run for the cause and ask Klaudius about it, then start again
Three runs in a row finished within a minute without doing any work	Stops	Open the last run to see what stopped it
Your Claude or ChatGPT sign-in ran out	Stops	Sign in again from the notice on the Runs page, then start the run again
Your usage limit was reached	Pauses, says when it resumes, and carries on after the reset	Nothing. If it keeps hitting the limit with nothing finishing in between, it stops; start it again once your window reopens
Your internet connection dropped	Holds off and starts more runs once it's back	Nothing, unless it isn't back within 2 hours: then it stops and tells you

A single run that stops on your sign-in or your usage limit picks up where it left off: sign in again, or send it a message once the window reopens.

Quitting the app or restarting the computer stops every run, and closing a laptop lid puts the computer to sleep even while work is in flight. On Linux, closing the window also quits the app, and on a Chromebook, ChromeOS's own power settings decide when it sleeps. Runs don't pick up again after a quit or restart: start Run Klaudius again when you're back. See Runs for leaving it working.

Running low on disk space

When your disk, or the one your Klaudius folder is on, is nearly full, a notice at the top of the app says so. Once a disk is full, Klaudius can't save its work, and the app can't install updates.

Klaudius clears each website's build files after a successful deploy. To clear what's left, ask Klaudius to free up disk space: it removes only files it can rebuild, never a website's source or your clients' data.

"Klaudius couldn't connect to its own tools"

Security software that scans web traffic (an antivirus web shield, for example) can block Klaudius from reaching its own tools. If a run stops with this message, follow what it says: usually, pause that protection or add an exception for Klaudius, then quit and reopen Klaudius.

Updates aren't arriving

On a Mac, Klaudius can only update itself from your Applications folder: quit it, drag it into Applications, and open it from there. Settings → Klaudius folder shows when it last checked, and what to do if something went wrong. See Updates.

On Linux, if Update not installed appears, press Open download page and open the file you download to install it. Your licence, settings and Klaudius folder are all kept.

Getting help from us

If Klaudius can't make sense of what's happening, send us what it told you from Help → Message us, or email hello@klaudius.dev, and we'll dig in. We read every message and reply by email.

To send us the details of one conversation, use Settings → Report a problem: pick the conversation and press Review and send. You see exactly what's included before anything leaves your computer.