Troubleshooting

Connection issues

Test Connection fails with LM Studio or Ollama

Confirm the server is actually running:
- LM Studio: Local Server tab shows running on port 1234.
- Ollama: curl http://localhost:11434/api/tags returns a model list.
Check the URL in Settings → Connection: it should point at the server root (http://localhost:1234, http://localhost:11434), not a deeper endpoint path. Karpa builds endpoint paths itself.
Model identifiers must match your provider exactly. Use the model picker to fetch available models instead of typing from memory.

Karpa in Docker cannot reach my local model

Containers do not share your machine's localhost. Two things are required:

Run the container with --add-host=host.docker.internal:host-gateway (the compose file already does this).
In Settings, point the provider URL at http://host.docker.internal:1234 (LM Studio) or http://host.docker.internal:11434 (Ollama) instead of localhost.

See Installation.

Cloud provider rejects my API key

Keys live in session storage and are cleared when you close the browser; re-enter the key after reopening Karpa.
Verify the key on the provider's dashboard and check you selected the right provider row in Settings.

Translation issues

Translations are slow

Local: use a smaller or more heavily quantized model (Q4_K_M is a good trade-off). See Choosing a Model.
Long texts are chunked (up to 2000 characters per chunk) and translated sequentially; watch the progress bar rather than assuming it hung.

Results look wrong or off-tone

Lower temperature toward 0.2 for faithful output.
Try a different tone (Standard, Formal, Casual, Technical).
Weak local models may ignore tone instructions; step up a model size if tone matters for your use case.

Grant notification permission when the browser asks, then enable notifications in Settings → Notifications. Some operating systems also require notifications to be allowed for the browser or app itself.

My file upload is rejected

Binary formats (PDF, DOCX, images) are not supported. Convert to .txt, .md, or another text format first. See the full list in File Translation.

The app looks broken or behaves strangely

Reset to a clean state:

Export a backup from Settings → Data → Export Data.
Use Settings → Data actions to clear data or reset settings/onboarding.
Still broken? Open an issue with your OS, version, and provider setup.