Authentication problems
A provider is installed and detected but still will not run a turn.
Almost every authentication problem is really a state-confusion problem. Harmony can see that a provider binary exists. It cannot see whether you are signed in, and it does not hold your provider credentials.
Place the failure first
| State | Who knows | How to check |
|---|---|---|
| Detected | Harmony | nala doctor |
| Authenticated | The provider | The provider's own command |
| Entitled | The provider's billing | The provider's account page |
IMPORTANT
A provider appearing in Harmony means "I can start this program." It does not mean "this will produce a model turn."
The provider pane opens and closes immediately
Symptom: a provider launches, flashes, and exits.
Likely cause: not authenticated. Most agent CLIs exit rather than prompt when they have no credentials and no TTY expectation.
Safe diagnostic — run the provider directly, outside Harmony:
claude
Expected evidence: the provider's own error message about sign-in.
Repair: complete that provider's login flow in your own terminal, then relaunch from Harmony.
When not to retry: do not relaunch repeatedly from Harmony hoping it takes. Harmony is starting the program correctly; the program is refusing.
Authenticated in my terminal but not under Harmony
Symptom: the provider works standalone and fails when Harmony launches it.
Likely cause: environment difference. Your interactive shell loads a profile
that the launched process may not, so an API key exported in .bashrc or a
PowerShell profile is invisible to the child process.
Safe diagnostic
nala doctor --json
Compare the resolved executable against your own shell:
Get-Command claude | Select-Object -ExpandProperty Source
Repair: make the credential available without your shell profile — use the provider's own credential store, or set the variable at user scope rather than in a profile script.
SECURITY
Exporting an API key globally makes it readable by every process you run, including agents. Prefer the provider's own credential store.
The turn starts and then fails on the model
Symptom: the provider accepts the prompt, then errors mentioning a model, quota, or rate limit.
Cause: entitlement, not authentication. You are signed in; the plan does not cover what was requested.
Repair: choose a model your plan includes.
NOTE
Harmony cannot read your plan, quota, or rate-limit state for any provider and does not guess. Errors in this category are answered by the provider.
An external harness cannot authenticate
Symptom: a user-managed ACP harness fails to authenticate while first-party providers work.
Context: user-managed harnesses run under credential isolation — their credentials are deliberately not shared with other providers in the workspace. That is the intended boundary, not a bug.
Repair: supply that harness's credentials through its own configuration.
Nothing above matches
nala doctor --json
WARNING
Review the output before sharing. It contains absolute paths, workspace and repository names, and provider details, which routinely reveal usernames and unreleased project names.