Troubleshooting

Ollama Not Detected

Symptom: Wilson reports it cannot connect to Ollama, or local model responses fail.

Solutions:

1. Verify Ollama is running:

   ollama list

2. If not installed, install from ollama.com.
3. Pull the default model:

   ollama pull llama3.2

4. Ensure Ollama is serving on the default port (http://localhost:11434). If you changed the port, set the OLLAMA_HOST env var.

---

API Key Errors

Symptom: Invalid API key or 401 Unauthorized when using a cloud provider.

Solutions:

1. Check that your key is set in the environment:

   echo $OPENAI_API_KEY    # OpenAI
   echo $ANTHROPIC_API_KEY # Anthropic

2. Verify the key is valid and has not expired.
3. Use the provider prefix when selecting a model:

   wilson --model claude-sonnet-4-20250514

4. If using .env, ensure it is in your home directory (~/.openaccountant/.env) or project root.

---

Import Parsing Failures

Symptom: Failed to parse CSV or transactions are missing after import.

Solutions:

1. Check the CSV format. Wilson supports Chase, Amex, Bank of America, and generic CSV. The file must have a header row.
2. Verify encoding. CSVs must be UTF-8. Re-export from your bank if you see garbled characters.
3. Date column issues. Ensure dates are in MM/DD/YYYY or YYYY-MM-DD format.
4. Try generic mode. If auto-detection fails:

   wilson import --format generic transactions.csv

5. OFX/QIF files. Wilson supports OFX (v1.x SGML and v2.x XML) and QIF. Ensure the file extension is correct (.ofx, .qfx, or .qif).

---

Duplicate Transactions

Symptom: The same transactions appear multiple times after re-importing.

Explanation: Wilson deduplicates using two mechanisms:

• File hash — the imports table tracks SHA-256 hashes of imported files.
• Transaction external_id — each transaction gets a unique ID based on date, amount, and description.

If you see duplicates:

1. You may have imported overlapping date ranges from different files. Wilson handles this — duplicates are skipped.
2. If duplicates still appear, check for slight differences in the CSV (extra whitespace, different date formats).

---

Database Issues

Symptom: SQLITE_CORRUPT or database is locked errors.

Solutions:

1. Locked database. Close any other Wilson instances or SQLite clients accessing ~/.openaccountant/data.db.
2. Corruption. Back up and rebuild:

   cp ~/.openaccountant/data.db ~/.openaccountant/data.db.bak
   wilson --run "re-import my transactions"

3. Check disk space. SQLite fails silently on full disks.

---

LLM Provider Timeouts

Symptom: Requests hang or time out when using cloud LLM providers.

Solutions:

1. Check your internet connection.
2. Verify the provider status page (e.g., status.openai.com).
3. Switch to a local model temporarily:

   wilson --model ollama:llama3.2

4. For slow Ollama responses, ensure your machine meets the model’s memory requirements. Smaller models like llama3.2 need less RAM.

---

License Key Issues

Symptom: Paid skills fail with Invalid license key or License required.

Solutions:

1. Verify your key is set:

   echo $OPENACCOUNTANT_LICENSE_KEY

2. Check that your subscription is active at polar.sh.
3. Re-validate:

   wilson --run "validate my license"

---

Wilson Not Found After Install

Symptom: command not found: wilson after running the install script.

Solutions:

1. The installer places Wilson at $HOME/.local/bin/wilson. Ensure this is in your PATH:

   export PATH="$HOME/.local/bin:$PATH"

2. Add the line above to your ~/.zshrc or ~/.bashrc and restart your shell.
3. Verify the binary exists:

   ls -la ~/.local/bin/wilson

---

Getting Help

If your issue is not listed here:

1. Search GitHub Issues.
2. Open a new issue with your Wilson version (wilson --version), OS, and the full error message.
3. Join the discussion on GitHub Discussions.