Troubleshooting Kairo Code Desktop

Start with the message shown in the Desktop app. Do not repeatedly retry an action until you know whether it may already have changed files, sent a message, submitted a form, or updated an external system.

The app will not open

1. Confirm that Kairo Code.app is in Applications, not still running from the DMG window.
2. Open Finder, Control-click Kairo Code, and choose Open when macOS asks you to confirm a controlled preview build.
3. If the local service exits repeatedly, choose Open Logs on the startup screen. Keep the full log locally and note the first error after the version line.
4. Check that the running version and source revision match the release record supplied with your installer. If they do not match, stop and reinstall that approved build.

Do not disable Gatekeeper, remove quarantine attributes, or make system-wide security exceptions.

A Task does not start or resume

• Reopen the same Project root or the same ordered set of roots used when the Task was created.
• Check the Task for a pending approval or question. A blocked request is waiting for your decision, not running in the background.
• If the app reports a local-service failure, use Open Logs and restart Kairo Code once. Durable Task history remains; an in-progress model or tool call may need to be started again.
• Never create a second Task to repeat a write until you have inspected the original Task's files and final status.

A model connection fails its test

Open Settings → Personal → Models & providers, select the connection, and choose Test connection.

Message	What to check
Authentication failed	Replace the provider credential. Never paste it into a Task or support message.
Model unavailable	Confirm the exact model ID and account access.
Rate limited	Wait for the provider's indicated delay before testing again.
Timeout or endpoint unavailable	Check the Base URL, VPN, proxy, and provider status.

A command or tool is denied

Read the denial and effective permission Profile before retrying. Approval can authorize only the displayed operation within the Project roots and the administrator-owned ceiling.

• Review the exact tool, arguments, destination, and requested duration.
• If the operation is unnecessary, steer the Agent toward a narrower alternative.
• If organization policy or a required sandbox blocks it, preserve the visible error code and ask your administrator to review that policy.

Permission boundaryDecision required

Kairo Code

Workspace write · local command

Know what will happen before it runs

Run affected testsDecision required

1. 01Review action
2. 02Choose once or rule
3. 03Inspect receipt

Browser work stops or the outcome is unknown

A website may have accepted an action even when Kairo Code did not receive its result. Inspect the visible page and the site's real state before another click, submission, payment, publication, or message.

• After a redirect or origin change, select the intended tab and review the new origin approval.
• After stopping or reconnecting paired Chrome, inspect the page before retrying.
• If pairing was revoked, pair Chrome again or explicitly choose the built-in Browser for a new Task; Kairo Code does not silently switch providers.
• If Browser capacity is full, permanently delete an obsolete Task only after reviewing its files and history. Hiding the panel or archiving a Task does not release uncertain Browser receipts.

Memories or Subagents look incomplete

For memories, open Settings → Advanced → Memory & learning. Consent changes apply to new Tasks; they do not rewrite the policy captured by an existing Task. An unresolved deletion receipt is not a successful deletion—keep it and contact support if retry remains unavailable.

For Subagents, open the collaboration view before delegating the same write again. Restarting the app preserves durable child history but does not resume an in-memory model or tool call. A capacity rejection creates no child Task; wait for or stop an existing child before retrying.

A Plugin does not activate

Open Settings → Extensions → Plugins, reopen the failed Plugin, and review the displayed capability change and failure reason. Activation applies to new Tasks; an already running Task keeps its earlier capability snapshot.

Prepare a safe support report

Include:

• the exact visible action and error message;
• the Kairo Code version and source revision shown by the app;
• whether the Project has one root or multiple roots, and the active permission Profile; and
• only the smallest relevant excerpt opened through Open Logs.

Remove credentials, prompts, source content, private paths, internal endpoints, and personal data. Do not attach a complete log or an unreviewed Task transcript.

Still stuck

Stop the affected Task and contact your organization's approved Kairo Code support channel. Keep the original Project and Task until support has reviewed the failure; deleting them can remove the only durable evidence needed for recovery.