Troubleshooting Guide
Relevant source files
The following files were used as context for generating this wiki page:
This guide provides technical resolution steps for common issues encountered when using ollacc to interface Claude Code with the Ollama Cloud API. It covers authentication failures, model availability issues, environment configuration, and installation persistence.
ollacc acts as a thin wrapper that manages environment variables and model selection for the Anthropic SDK, routing requests directly to https://ollama.com without requiring a local Ollama server.
Sources: README.md:1-25, lib/auth.sh:48-53
Authentication and API Key Issues
Authentication issues typically manifest as 401 Unauthorized errors from the Ollama API. The ollacc system stores the API key in a configuration file with restricted permissions.
Common Symptoms
- 401 Unauthorized: Occurs when the
ANTHROPIC_AUTH_TOKENis invalid or expired. - Permission Denied: Occurs if the configuration file permissions are modified from the default
chmod 600.
Resolution Steps
To resolve authentication issues, users should clear the existing key and re-authenticate.
- Clear Saved Key: Use the built-in management flag to remove the token from the config.
ollacc --key-clear - Re-prompt: Running
ollaccagain will trigger theauth_prompt_if_missingfunction, which displays the setup instructions and accepts a new key.
Sources: README.md:104-106, lib/flags.sh:22-31, lib/auth.sh:14-46
Authentication Data Flow
The following diagram illustrates how ollacc handles API keys and environment variables.
The empty ANTHROPIC_API_KEY is a critical requirement to ensure the Anthropic SDK respects the ANTHROPIC_AUTH_TOKEN.
Sources: lib/auth.sh:48-53, README.md:144-152
Model Selection and Catalog Issues
Issues in this category include models missing from the menu or saved default models no longer functioning.
Missing Models
The "Popular" model list is generated by scraping https://ollama.com/search?c=cloud and intersecting it with the user's authorized catalog via https://ollama.com/api/tags.
| Issue | Resolution |
|---|---|
| Model not in top 10 | Use option 11) [Custom] in the menu and type the exact model name. |
| Network Timeout | ollacc will fall back to the authorized catalog order or a hardcoded last-resort list. |
| Stale Default | If a saved default model is removed from your catalog, use ollacc --model-clear. |
Sources: README.md:108-120, lib/catalog.sh:27-80, lib/menu.sh:33-40
Catalog Resolution Logic
When fetching models, the system follows a specific priority order to handle network or API failures.
Sources: lib/catalog.sh:27-80
Installation and Environment Issues
"command not found" Errors
If ollacc is not recognized after installation, the shell alias likely has not been loaded into the current session.
- Manual Source: Run
source ~/.zshrc(or the specific RC file identified during install). - RC File Priority: The installer searches for files in this order:
.zshrc,.bashrc,.bash_profile,.profile.
Configuration File Issues
The configuration is stored in ~/.ollacc/config.
- Permissions: The directory is
700and the config file is600. The installer and config functions (likeconfig_set) enforce these permissions. - Manual Edits: Users can manually edit the file, but must maintain the
KEY="..."shell variable format.
Sources: install.sh:37-104, lib/config.sh:44-50, README.md:112-116
Summary of Management Flags
These flags can be used to troubleshoot and reset the application state without re-installing.
| Flag | Function | File Reference |
|---|---|---|
--model-clear | Removes OLLAMA_CLAUDE_DEFAULT_MODEL from config. | lib/flags.sh:12-21 |
--key-clear | Removes ANTHROPIC_AUTH_TOKEN from config. | lib/flags.sh:22-31 |
--model <name> | Bypasses the menu for a single execution. | README.md:88 |
Sources: lib/flags.sh:10-34, README.md:86-93
Uninstallation Cleanup
If the system needs to be completely reset, the uninstall.sh script removes the markers and aliases from shell RC files. It also provides an interactive prompt to delete the ~/.ollacc/ directory and its associated API keys.
Sources: uninstall.sh:24-64