Troubleshoot mogick setup and authentication

Use this guide when OAuth device-code authentication does not complete, credentials are rejected, a token expires, or other credentials override a third-party API key. For timeouts, DNS, or proxy failures, troubleshoot the model connection instead. If the mogick command is missing, resolve installation and startup first.

Run authentication diagnostics first

mogick doctor

Review the config, models, and auth sections. If authentication looks valid but model calls still fail, run a real network check:

mogick doctor --check-network

Choose the symptom that matches your issue:

Symptom	Start here
mogick setup displays a URL and device code, but no browser opens	The browser does not open
The device code is invalid or expired, or authorization does not complete	Device-code authorization failed
auth.json is missing after setup	Credentials were not written to the expected directory
A token expired, INVALID_OAUTH_TOKEN appears, or login is requested repeatedly	OAuth token refresh failed
An API key is configured, but the service returns 401	The API key is not being used
Authentication fails in only one project	Project credentials override global credentials
Authentication passes, but setup's final connection check fails	Separate authentication from model connectivity

The browser does not open

mogick setup uses the OAuth device-code flow. If the browser does not open automatically, complete authorization manually:

1. Keep the current mogick setup process running.
2. Copy the full URL displayed in the terminal and open it in any available browser.
3. Enter the device code shown in the terminal and authorize access.
4. Return to the terminal and wait for the CLI to detect completion and save the credentials.

For a remote host or SSH session, open the URL in a browser on your local computer. Do not share the device code; anyone with a valid code may be able to complete the pending authorization.

If the terminal does not display the URL or device code, end this process and run again:

mogick setup

Device-code authorization failed

If the browser reports that the code is invalid or expired, or authorization does not complete:

1. Close the currently failed authorization page.
2. End the mogick setup that is still waiting.
3. Rerun mogick setup, using the newly generated URL and device code.
4. Keep the terminal open after authorization and wait for the CLI's final result.

Each device code belongs to one setup process and can be used only once. After restarting setup, use the newly generated code.

If the account or organization lacks access to the service, the local credential file is not the cause. Verify the signed-in account and its service permissions.

Credentials not written to expected directory

By default, OAuth credentials are written:

<config-dir>/auth.json

If MOGICK_CONFIG_DIR is set, Mogick writes global auth.json to that directory. Run doctor to confirm the effective path:

mogick doctor

Then check:

• The configuration directory reported by doctor is the one you expect.
• The current user can write to that directory.
• auth.json contains valid JSON.
• Setup was not run under a different system account or shell environment.

Do not hide permission problems by rerunning setup as an administrator or with sudo; credentials may then become unreadable to the normal user. Correct ownership or permissions and run mogick setup as the account that normally uses Mogick.

OAuth token refresh failed

Mogick uses the refresh token to renew an expired access token. If the model service returns INVALID_OAUTH_TOKEN, the CLI forces a refresh and retries the request automatically.

If it still fails after trying again:

mogick setup
mogick doctor

Reauthorization updates credentials. Setup also adds the official provider and fills missing default/lightweight model settings, preserving existing providers and explicit choices. See Sign out and switch accounts.

If you are still prompted to log in repeatedly after re-authorization, focus on checking:

• Whether the auth check still reports an expired or invalid token.
• Whether there is a project-level .mogick/auth.json with higher priority in the current working directory.
• Whether the system clock is incorrect; OAuth validation depends on accurate timestamps.
• Whether the call failure actually came from the network, provider permissions, or model configuration, rather than the token itself.

The API key is not being used

For a direct connection to an OpenAI-compatible service, store the API key in auth.json:

{
  "api_key": "<your-api-key>"
}

At runtime, a valid OAuth access token takes precedence over api_key. If a third-party service returns 401, check whether the effective auth.json still contains an access_token or refresh_token for another provider.

Back up the credential file before changing it. For a direct single-provider connection, follow Configure a third-party model, place api_key at the top level of auth.json, and verify llm.provider, llm.base_url, llm.model, and llm.models[] in config.json. For multiple providers, use auth.providers.<provider-id>. See Authentication and models.

Never put an API key in config.json, command arguments, screenshots, or issue reports.

Project credentials override global credentials

Mogick can have two levels of authentication files at the same time:

Location	Scope	Priority
<workspace>/.mogick/auth.json	Current project	High
<config-dir>/auth.json	All projects of the current user	Low

If authentication fails in only one project:

1. Run mogick doctor in the affected project directory to identify the loaded credential file.
2. Check whether .mogick/auth.json exists under the project.
3. Compare the global and project files for an expired token, incorrect API key, or invalid JSON.
4. Back up and correct the unwanted project override, then run doctor again.

Never commit auth.json. When sharing its structure, remove all values and retain field names only.

Separate authentication from model connectivity

After authorization, mogick setup also tests the LLM connection. A failure at the end of setup does not necessarily mean OAuth failed.

Use doctor results to identify the likely cause:

Result	Likely cause
auth reports a missing or expired token, or refresh failure	Authentication issue; rerun setup and check credential precedence
auth is normal, but config reports an error	config.json syntax, field or loading path problem
auth passes, but models or the network check times out	Provider URL, proxy, firewall, or service-availability issue
model not found or a similar 400 response	Incorrect model ID or provider configuration; repeated login will not help
401 response	Invalid credentials or the wrong credential type
403 response	The account, organization, or model lacks permission, or a server-side policy blocks access

For timeout, DNS, proxy, or certificate errors, run mogick doctor --check-network and verify the service URL. For third-party model IDs and provider settings, see Configure a third-party model.

Generate diagnostic information

If the cause is still unclear, export detailed diagnostics:

mogick doctor --verbose --check-network --export ./mogick-auth-report.md
mogick doctor --verbose --logs-path ./mogick-auth.log

It is recommended to provide:

• Operating system and installation method.
• Whether you use OAuth or an API key, without the credential value.
• Complete error message and the stage at which the error occurred.
• Status of config, models, and auth in doctor.
• Whether the problem only occurs in a certain project directory.

Before sharing reports or logs, redact API keys, access tokens, refresh tokens, device codes, proxy credentials, usernames, and sensitive paths.

Confirm that the problem has been solved

mogick doctor
mogick doctor --check-network
mogick run "Reply: authentication succeeded"

The issue is resolved when doctor reports no blocking auth errors, the network check authenticates successfully, and the model returns a valid response.

Related documents

• Authentication and models (setup)
• Configuration overview
• Configure third-party model access
• Data directories and environment variables
• Troubleshoot installation and startup

Path placeholders <config-dir> and <db-path> refer to the effective profile/channel paths; see Data directories.