Provider errors

Start with the message shown in the Agent auth failed or Agent run failed notice. The full error remains in the agent activity log and can identify the provider setting that needs to change.

​

The provider says a credential is missing

Open Settings, then API keys. Check whether the selected provider shows Key set, Using login, Missing, or Optional. Adding a key allows future requests to use that provider. When you enter a key in the panel, DocWriter stores it in ~/.docwriter/keys.env with permissions limited to your operating system user. Removing a key stops DocWriter from using that saved value, but the provider may still work through an environment variable or command line login. Process environment variables and project .env files take precedence over ~/.docwriter/keys.env. Restart DocWriter after changing a shell environment variable. A wrong value in the environment can continue to override a correct value saved in the panel.

​

Claude Code login expired

/login is typed inside Claude Code in a terminal — not in the DocWriter UI.

1. Open a terminal on the same computer that runs DocWriter.
2. Enter claude and press Enter. Wait until the session is running.
3. Type /login and press Enter. Finish the browser sign-in.
4. In DocWriter, open Settings → API keys. Claude should show Using login.
5. Retry the agent request.

Keep the Anthropic key field empty for subscription login. If a key is set in the panel or as ANTHROPIC_API_KEY, DocWriter bills API usage instead — remove the stored key and unset the env var to use login again. Choose New session if the provider still tries to resume an expired conversation. New session clears the saved provider conversation, agent activity for the current session, temporary scratch files, and pending proposals. It keeps workspace files, comments, rules, hooks, and settings. Copy any proposal text you need before choosing it.

​

Other command line logins expired

Codex can also use an existing command line login. Run that provider’s login again in a terminal on this computer, then retry. Choose New session if the provider still tries to resume the expired conversation.

​

The selected model does not exist

Open the model control and choose another model listed for the current provider. Changing the model affects future agent requests. Your workspace files stay the same. A custom model identifier can be saved in the interface even when the provider does not allow the account to use it. Model access can depend on the account, subscription, region, and API endpoint. If OpenAI reports that codex-mini does not exist, choose an available GPT model. If Claude reports that enabled thinking is not supported, choose another Claude model.

​

The provider reached a quota or rate limit

Wait for the limit to reset, or select another provider that has working credentials. Switching providers starts a separate provider conversation. The new provider starts without the old provider’s saved conversation. Cancel the current run if queued messages should not run after the limit resets. When you cancel the run, DocWriter closes it and clears queued messages. Some provider work may continue. Completed tool calls, comments, and proposals remain. Provider charges are not reversed.

​

A saved session cannot resume

Open Settings, then Sessions, and choose another session. Start a new session when the saved provider conversation no longer exists. Choosing another session changes which saved provider conversation the agent continues. Your workspace files stay the same. Starting a new session removes the current session’s activity and pending proposals, so copy proposal text you need first.

​

The provider starts but a tool fails

Open the transcript and inspect the failed tool result. Confirm that the file is inside the workspace and that the selected provider supports the requested tool. Retry only after you fix the stated cause. A retry sends another provider request, can use more quota, and may repeat a command if the first attempt completed before reporting an error. Check the workspace before retrying any action that writes or deletes files. Read Privacy and safety to understand what a provider can read and which commands can run.