Reference

Troubleshooting

What to do when a check is blocked, an account needs signing in, the engine does not answer, a message waits, or Chrome stops connecting.

Start with two commands. claude-rotation status says whether the scheduler and the engine are running and which account is in use. claude-rotation diagnose looks further: files, background agents, the engine's port, the shell line and each account's folder. claude-rotation logs shows what the last checks decided. See Install › Check it is working and Files and logs.

An account needs signing in

claude-rotation accounts says "needs sign-in" beside it, and the app shows it on Accounts. Rotation does not start new sessions there until it is signed in again.

• In the app, open the account's menu and choose Sign In Again…. Claude Code's own sign-in opens in the Mac's browser.
• From a terminal, claude-rotation sign-in ACCOUNT, or claude-rotation repair to go through every account that needs it.

claude-rotation check also repairs these accounts before it checks.

A check was blocked

The log says outcome=blocked, and Activity says "Blocked". No account had room to switch to: every one is at a limit or a hard cap, held out, or needs signing in. Running sessions keep their accounts.

• Sign in any account that needs it (above).
• Look at Accounts for when each one resets, and at caps you may have set.
• The week plan and its alerts say ahead of time when the accounts run out at this week's pace.

On an install that still rotates with cswap, from 12 Nov 2026 every check is blocked with reason=cswap-retired until the accounts are moved: see Rotation › Moving accounts to Kairos.

A check failed or timed out

outcome=error exits 1, and outcome=timeout exits 124 after 120 seconds. Run claude-rotation check yourself to see the error, and look in logs/scheduler.err.log. "A check is running; try again in a minute." means another check or switch held the lock; it ends by itself. A slow Mac can allow a check longer: see Settings and config › Fixed values.

The engine does not answer

• The web dashboard says "Open this page with: claude-rotation dashboard": the engine restarted and made a new key. Run the command again.
• The iPhone says "Kairos on this Mac is not answering.": the Mac is asleep, off the network, or Kairos is not running on it. See Pairing.
• install says the dashboard port is in use by another service: another app took port 47615. Choose another with claude-rotation config, then run claude-rotation install.
• It says another copy of Kairos is running outside its background item: quit that copy and try again.
• Settings › General › About shows an older "Kairos on this Mac" than the app: bring the engine up to date: see Updates › The engine.

The engine's own log is logs/dashboard.log.

The iPhone shows less than the Mac

When the Mac runs an older Kairos than the phone expects, a screen says "Kairos on the Mac is older than this app: update it to see …". Features new in a version, such as the planned line, show nothing until the Mac has that version. Update Kairos on the Mac.

A message to a session waits

Under Message this session, Kairos says when Claude Code will not deliver at once:

The pause before a limit, the resume after it, and the question about unusual use are messages too, so they wait the same way. See The capacity guard.

Claude in Chrome stops connecting

When Chrome was closed and opened again, an older session's link to it can stay stuck while new sessions connect. Kairos tells the session, or starts it again while it is idle; /exit and then claude --resume in that session connects at once. See Claude in Chrome › A stuck link.

An unusual-use alert

A session used far more than usual, or the Mac is short of disk or memory. Kairos asks the session to clean up and shows its reply. See Unusual use and Disk.

Still stuck

Write to support@matihlabs.com with what claude-rotation diagnose printed. Read it first: it names your own folders and accounts, so remove anything you would rather not send.