Troubleshooting

Common issues and their solutions when using Conjra.

Error types

APIError

Thrown when a provider API returns an error:

[{provider}] {status} — {message} (code: {code})

Common causes: Invalid API keys, expired tokens, incorrect request parameters, rate limiting.

Fix: Verify your credentials with conjra status, check the provider dashboard for key validity, and ensure your parameters match the provider API docs.

AuthError

Thrown when provider authentication fails:

Authentication failed for provider "{provider}": {message}

Common causes: Revoked API keys, insufficient permissions, expired tokens.

Fix: Reconnect the provider with conjra remove {provider} then conjra add {provider} with fresh credentials.

ProviderNotConnectedError

Thrown when a tool is called for a provider that has no stored credentials:

Provider "{provider}" is not connected. Run: conjra add {provider}

Fix: Run conjra add {provider} with valid credentials.

ToolExecutionError

Thrown when a tool execution fails unexpectedly:

Tool "{toolName}" failed: {cause.message}

Common causes: Network errors, unexpected API response formats, internal errors.

CLI issues

Command not found

Run npm bin -g to find where npm installs global binaries and ensure it is in your PATH.

conjra add fails silently

Ensure the provider name is spelled correctly. Run conjra add without arguments to see the error message.

conjra init fails

Check that the config file directory exists. Conjra creates parent directories automatically, but may fail if the home directory is not writable.

MCP connection issues

Editor does not discover Conjra tools

1. Verify the editor is configured: conjra status
2. Restart the editor after running conjra init
3. Check the editor logs for MCP connection errors

Claude Code MCP connection fails

Check ~/.claude/settings.json for the conjra entry. The path in args must point to the installed conjra dist/mcp/server.js.

Cursor shows "MCP server not found"

Ensure .cursor/mcp.json exists in your project root (the directory you opened in Cursor).

Keychain issues

Keychain vault not found

The vault directory ~/.conjra/vault/ is created automatically when you first run conjra add. If missing, try connecting a provider.

Cannot decrypt vault file

Vault files are machine-locked. If you switch machines, you need to reconnect your providers. Copying ~/.conjra/vault/ between machines does not work.

Credentials not found

Run conjra status to verify the provider is connected. If not, reconnect with conjra add {provider}.