Troubleshooting

Organized by category. Each issue lists the symptom, the likely cause, and steps to resolve.

---

Providers

Invalid API Key

Symptom: Requests fail with 401 or “invalid API key” error.

Fix:

1. Open Settings → Providers and select the affected provider.
2. Re-enter the API key — copy directly from the provider’s dashboard.
3. Send a test message to confirm.

Rate Limits

Symptom: 429 error or “rate limit exceeded.” Requests succeed intermittently.

Fix:

1. Wait 60 seconds — most rate limits reset within 1 minute.
2. Check your provider dashboard for usage and tier limits.
3. Switch to a different model or provider temporarily.
4. For sustained high-volume work, upgrade your API tier.

Request Timeout

Symptom: Responses hang or fail with timeout after 30–120 seconds.

Fix:

1. Check the provider’s status page for incidents.
2. Reduce context size — switch to a shorter context strategy or start a new conversation.
3. Try a smaller model from the same provider.
4. Verify network connectivity.

OpenAI Organization ID

Symptom: OpenAI requests fail with “organization” errors.

Fix: Enter your Organization ID in Settings → Providers → OpenAI. Find it at platform.openai.com/account/organization.

Google API Setup

Symptom: Gemini requests fail with authentication or project errors.

Fix:

1. Confirm you have a Google Cloud project with the Generative Language API enabled.
2. Verify your API key is associated with the correct project.
3. Check that billing is enabled — some Gemini models require an active billing account.

Ollama Not Running

Symptom: Ollama models unavailable or connection refused.

Fix:

1. Run ollama serve in a terminal.
2. Verify with ollama list.
3. Confirm the URL in Settings → Providers → Ollama matches (default: http://localhost:11434).

Model List Not Updating

Symptom: New models from a provider do not appear in the model picker.

Fix: QARK caches model lists with a 5-minute TTL. Wait 5 minutes or restart the app to refresh. If using OpenRouter, new models may take time to propagate from upstream.

---

RAG

No Relevant Results

Symptom: Queries against uploaded documents return irrelevant chunks or nothing.

Cause 1: Threshold too aggressive. The RAG threshold determines when documents are sent through the vector pipeline vs. injected directly.

Fix: Lower the threshold in per-conversation RAG settings. A lower threshold routes more documents through full RAG processing.

Cause 2: Documents still processing. The RAG pipeline may still be chunking and embedding.

Fix: Check the document panel for processing status. Wait until all documents show ready. Large documents (500+ pages) can take several minutes.

Cause 3: Wrong embedding model. The embedding model may not handle your content type well.

Fix: Try a different embedding model with more dimensions. Technical/specialized content benefits from larger models.

Documents Stuck in Processing

Symptom: Documents show pending or processing status indefinitely.

Fix:

1. Verify your embedding provider is configured and the API key is valid.
2. Check that the embedding model is set in Settings → Tools & MCP → Documents & RAG.
3. Remove and re-attach the document.

---

Universal Overlay

Overlay Not Appearing

Symptom: The hotkey does nothing.

Cause 1: Hotkey conflict. Another application claimed the same global hotkey.

Fix: Change the hotkey in Settings → Sparks & Flows to an unused combination.

Cause 2: Missing permissions.

Fix:

• macOS: System Settings → Privacy & Security → Accessibility — ensure QARK is listed and enabled.
• Windows: Run QARK as administrator once to register permissions, then restart normally.
• Linux: Ensure your compositor supports overlay windows. On Wayland, additional permissions may be needed.

Overlay Dismisses Immediately

Symptom: The overlay appears briefly then vanishes.

Fix: Check Settings → Sparks & Flows → Dismiss on blur. If enabled, clicking outside the overlay closes it. Disable this setting, or use the pin icon in the overlay header to keep it visible.

---

MCP

Server Not Connecting

Cause 1: Wrong command path.

Fix: Run the command manually in a terminal. Use an absolute path if PATH resolution fails.

Cause 2: Missing environment variables. The subprocess only sees variables explicitly configured in QARK — not your full shell environment.

Fix: Add every required variable in the server’s environment configuration.

Cause 3: Server not installed.

Fix: Install the MCP server package (e.g., npm install -g @modelcontextprotocol/server-name) and verify by running it manually.

Cause 4: nvm/pyenv not found. QARK spawns stdio servers using a login shell, but your shell profile may not be configured correctly.

Fix: Verify that running bash -l -c "which node" (or the relevant command) returns the correct path.

Tools Not Appearing

Symptom: Server shows connected but no tools appear in @mention.

Fix:

1. Check the server’s discovered tools list in Settings → MCP Servers.
2. Verify individual tools are not disabled.
3. Ensure the server’s tool manifest is being sent correctly on connection.

---

Costs

Unexpectedly High Spending

Cause 1: Context strategy sending full history. The all strategy sends every message to the model each turn, multiplying costs as conversations grow.

Fix: Switch to auto_compact or token_budget for long conversations.

Cause 2: Expensive compaction model. Context compaction triggers automatically and uses whichever model is configured.

Fix: Set the compaction model to an inexpensive option in Settings → Sparks & Flows → Default compaction model. A local model (Ollama) makes compaction free.

Cause 3: Thinking tokens accumulating. Extended thinking generates additional tokens billed separately.

Fix:

1. Check the per-message token breakdown — thinking tokens are listed separately.
2. Disable thinking on conversations where deep reasoning is not needed.
3. Reserve thinking for complex analysis tasks.

Cause 4: Multi-agent workflows. Each sub-agent in a pipeline (like the Review Article Writer with 8 sub-agents) incurs its own token costs.

Fix: Check the budget dashboard for per-model breakdown. Use cheaper models on mechanical sub-agents (formatting, combining). Use the cost ledger to identify which agents drive spending.

---

Export

PDF Export Failing

Symptom: PDF export produces an error.

Cause: No Chromium-based browser found. PDF export requires Chrome, Arc, Brave, Edge, or Chromium installed on your system.

Fix: Install any Chromium-based browser. Markdown and HTML exports work without a browser.

Asset Folder Issues

Symptom: Export succeeds but images/attachments are missing.

Fix:

1. Ensure the output directory has enough disk space.
2. Avoid special characters in the conversation name — they can cause folder creation issues.
3. Check that the {name}_assets/ companion folder was created alongside the export file.

Long Path on Windows

Symptom: Export fails on Windows.

Fix: Export to a shorter path like C:\Exports\. Windows has a 260-character path limit.

---

Database

Corruption

Symptom: QARK fails to launch, shows database errors, or behaves erratically.

Cause: SQLite file corrupted from system crash, forced kill, or disk error during write.

Fix:

1. Close QARK.
2. Locate ~/.qark/qark.db.
3. Copy the file as a backup before any repair attempt.
4. Try: sqlite3 qark.db "PRAGMA integrity_check;" — if errors, run .recover to extract data.
5. If unrecoverable, restore from your most recent backup.
6. Restart QARK.

Restoring a Backup

1. Close QARK.
2. Rename current database (e.g., qark.db → qark-current.db).
3. Copy your backup to ~/.qark/qark.db.
4. Restart QARK.