Troubleshooting

A short list of the real failure modes Kadro can produce today, with the actual fix for each. If your problem isn’t here, email support@kadrotools.aiand we’ll add it.

The app won’t open / Gatekeeper warning

On builds released before Apple Developer ID notarization is enabled, macOS may show “Kadro” can’t be opened because Apple cannot check it for malicious software or “the developer cannot be verified.”

The fix is to allow it once from System Settings → Privacy & Security using the Open Anyway button. The full walkthrough lives on the install page.

A provider says “not installed”

Open Settings → Providers. Each provider row is a single, fast check: is the CLI binary present on your PATH? Kadro deliberately does not run --version or read CLI auth files, because doing so on every refresh would add hundreds of milliseconds and parse multi-megabyte JSON.

If a provider is missing, the row shows the exact install command:

• Claude Code — npm i -g @anthropic-ai/claude-code → installs the claude binary.
• Codex CLI — npm i -g @openai/codex → installs codex.
• Gemini CLI — npm i -g @google/gemini-cli → installs gemini.

Run the install command in a real terminal — not inside a Kadro pane, since the pane may not yet have the updated PATH the installer wrote. After the install finishes, quit Kadro fully and relaunch so the app inherits the refreshed PATH.

Sign-in to each provider happens inside the pane itself, through that CLI’s own OAuth flow — Kadro does not manage their auth state.

The sign-in browser opens but the app never unlocks

Kadro’s sign-in flow finishes by deep-linking back into the app at kadro://auth/callback. If the gate stays on “Browser sign-in started”after you complete sign-in in the browser, it usually means the browser couldn’t hand the callback back to Kadro.

Things to try, in order:

1. Keep Kadro running. Some browsers prompt before opening a non-HTTP scheme — make sure you allowed the Open Kadro prompt rather than dismissing it.
2. Close any older Kadro installs you may have on disk. macOS routes kadro:// to whichever Kadro it registered most recently, and a stale build can intercept the callback.
3. Back in the app, the gate offers Sign in with Browser again. Click it to restart the flow with a fresh challenge.

If the gate shows a red Sign-in error with a message, the message is the actual reason — quote it when you contact support.

I’m signed in but the app says “no active trial or subscription”

Kadro’s subscription gate appears when your account is signed in but Kadro has not received an active Teams trial or Pro subscription for it. The gate offers four actions:

• Open pricing — opens /pricing in your browser, where you can start the 14-day trial.
• Account billing — opens /account, where you can manage an existing subscription.
• Sync access — re-checks your entitlement against the server. Use this after you finish the browser flow.
• Sign out — if you signed in with the wrong account.

A trial whose expiry date has passed is detected automatically and will route you back to this same gate.

The update banner never appears

Kadro checks for updates on launch and again about once an hour while running. If a new release was just published, give it a few minutes and check the sidebar above the profile row — the update pill appears there. A full restart of the app also forces an immediate check. The updater pulls from the manifest at github.com/alexci04/kadro-releases/releases/latest/download/latest.json; if you are on a network that blocks GitHub, the check will fail silently.

How crash diagnostics work

Crash and error diagnostics are off by default. Until you turn them on, nothing leaves your machine — not from the UI, and not from the Rust side either. Telemetry is gated on a recorded consent timestamp, not just a boolean, so first-launch errors before you opt in never get sent.

To enable: Settings → Privacy, toggle Crash diagnostics on. The renderer side starts sending immediately. The Rust side reads the consent file once at startup, so if you turn diagnostics on or off mid-session, Rust-side panics will pick up the change at the next launch.

To disable: toggle it back off. The UI stops sending right away. Stored consent does not include any account or device identifier beyond what Sentry needs for de-duplication, and diagnostics use a 30-day retention in an EU data region.

How to report a bug

Email support@kadrotools.ai with:

• what you were doing,
• what you expected,
• what actually happened (the exact wording of any error helps),
• your Kadro version (Settings → Account).

If you have crash diagnostics turned on, mention the rough timestamp — we can often correlate it with a Sentry event without you having to attach anything.

Related

• Install — Gatekeeper, system requirements, where data is stored.
• Getting started — the first five minutes inside Kadro.