Provider problems
A provider will not launch, exits immediately, or never produces a turn.
Before anything else, place the failure in the right state. Detected, authenticated, and entitled are three different things — see account and authentication.
The provider is not offered
Symptom: the provider does not appear in the orchestration bar or /provider
list.
Likely cause: its executable does not resolve on PATH in the environment
Harmony launched with.
Safe diagnostic
nala doctor
Expected evidence: a provider section listing what was detected and the resolved path for each.
Repair: install the provider's CLI, then restart Harmony so detection re-runs.
When not to retry: do not hand-edit configuration to force a provider that is not installed to appear. It will fail at launch instead of at detection, which is harder to diagnose.
The pane opens and exits immediately
Symptom: a provider pane flashes open and closes.
Likely causes
- Not authenticated.
- The provider errored during its own startup.
Safe diagnostic: run the provider directly, outside Harmony, in the same directory:
claude
Expected evidence: the provider's own error message. Harmony is launching it, so the provider's startup failure is the real error.
Repair: complete the provider's own login flow, then relaunch from Harmony.
It works in my terminal but not in Harmony
Symptom: the provider runs standalone but fails when launched by Harmony.
Likely cause: environment difference. Your interactive shell loads a profile that the launched process may not.
Safe diagnostic
nala doctor --json
Compare the resolved executable path and environment against what your own shell has:
Get-Command claude | Select-Object -ExpandProperty Source
Repair: make the provider resolvable without your shell profile — install it
to a location on the system PATH, or set the variable it needs at user scope
rather than in a profile script.
The turn starts, then fails on the model
Symptom: the provider is running, accepts the prompt, and then errors referencing a model or quota.
Likely causes
- Your plan does not include the requested model.
- A rate limit or spend cap was reached.
Expected evidence: the provider's own error text naming the model or limit.
Repair: select a model your plan covers.
IMPORTANT
Harmony cannot see your plan, quota, or rate-limit state for any provider, and it does not guess. Errors in this category are answered by the provider, not by Harmony.
Launch behaves inconsistently
Symptom: the same provider sometimes launches and sometimes does not.
Context: the provider launch path has been repaired several times in recent preview builds. If you are on an older preview, update first:
nala version
Compare against the version on the download page.
Repair: update to the current preview, then retry. If it persists on the
current build, capture nala doctor --json and report it.