Troubleshooting

Cause: App started minimized or OS blocked startup.

Fix: Check system tray overflow (^) on Windows. Relaunch Engine from Start menu. On Linux, confirm tray applet is running.

Cause: Extension disabled, wrong VS Code profile, or activation error.

Fix: Extensions → enable ContextMint. Reload window. Check Output → “ContextMint” for activation errors.

Cause: Dev layout vs packaged bundle path mismatch.

Fix: Engine → Settings → set backend path to shipped bundle. Reinstall latest Engine build. For source dev, point pythonPath at project venv.

Cause: API not listening on configured URL.

Fix: Engine → Start all. Verify http://localhost:8000/api/health. Check firewall blocking loopback. If using shared server, verify serverUrl and TLS.

Cause: Port 8000 in use, Python crash on boot, or zombie process.

Fix: Engine → Logs. Stop all, kill stray python/contextmint processes, change port in Settings if needed, Start all again.

Cause: Stale readiness poll, wrong serverUrl, or index status timeout.

Fix: Reload VS Code window. Confirm serverUrl has no trailing path typo. Engine → Server → restart server.

Cause: Optional Redis not running (some enterprise configs).

Fix: For local-first pilot, often safe to ignore if chat works. For team server, start Redis per deployment guide or disable Redis-dependent features in server config.

Cause: Ollama not running or wrong URL.

Fix: Engine → Ollama → Start / Restart. Install Ollama if missing. Default URL http://localhost:11434.

Cause: Chat model not pulled in Ollama.

Fix: Engine → Models → pull default chat model. Match model name in server defaults.

Cause: Missing embed model, GPU/CPU overload, or disk pressure.

Fix: Pull embed model in Models tab. Reduce concurrent indexing if tunable. Exclude large binary dirs via ignore rules.

Cause: Cold model load in Ollama.

Fix: Expected once per restart. Server runs background warmup; send a short ping message to load model before important queries.

Cause: Multi-root workspace, unregistered folder, or path mismatch on shared server.

Fix: Open the repo root folder. Engine → Indexing → confirm workspace listed. Enterprise: paths on server must match VS Code folder paths.

Cause: serverUrl points at localhost on remote host while browser test uses local machine.

Fix: Run Engine on SSH host or use team serverUrl reachable from remote extension host. Port-forward 8000 if required.

Cause: OIDC token missing or expired.

Fix: Re-authenticate per org SSO flow. Confirm oidcProviderId matches server. Check server audit for auth errors.

Cause: Permission errors, huge repo, or crashed background task.

Fix: Engine → Indexing → view errors. Engine → Logs. Trigger manual reindex. Exclude node_modules, build artifacts via ignore config.

Cause: File not indexed yet, wrong lane (Repo with empty index), or query mismatch.

Fix: Open file in editor (priority index). Wait for indexing. Attach file explicitly. Try Hybrid lane. Use symbol-rich query for code lookups.

Cause: Embed model changed, hash cache cleared, or watcher storm.

Fix: Stabilize embed model in Models tab. Check logs for repeated full reindex triggers. Pause bulk file operations during initial index.

Cause: Indexer exception, corrupt local store, or disk full.

Fix: Engine → Indexing error detail. Free disk space. Last resort: clear workspace index data and full reindex (backup first).

Cause: Expected — Repo lane refuses to speculate without evidence.

Fix: Switch to Work lane or accept Use Work lane banner. Attach notes or activate a session pack.

Cause: No packs built, no attachments.

Fix: Build session/repo packs. Attach markdown or spec files. Paste key context as attachment.

Cause: Ollama hang, cloud timeout, or SSE disconnect.

Fix: Click Cancel (send button). Restart Ollama. Check Logs. Reduce context size / attachment count. Retry with Local model only.

Cause: Invalid API key, provider outage, or cloudEnabled false.

Fix: Re-run Configure Cloud API Key. Enable contextmint.cloudEnabled. Check provider status. Inspect routing badge for tier used.

Cause: Image attachments disabled, wrong format, or file too large.

Fix: Enable contextmint.chat.imageAttachmentsEnabled. Use PNG, JPEG, or WebP — not SVG. Max 5 MiB per image. Check Output → ContextMint for validation errors.

Cause: No Ollama vision model installed.

Fix: Engine → Models → pull moondream (small) or llava. Restart Ollama if pull succeeded but route still fails. Cloud API keys do not replace a local VLM unless you explicitly select cloud vision.

Cause: Text-only model selected, or vision route fell back after VLM error.

Fix: Confirm Lens shows local or cloud vision route before send. Pull/update vision model. Check Engine → Logs for multimodal errors. Retry with Local model + installed VLM.

Cause: Large VLM on limited VRAM; chat + vision models competing.

Fix: Use moondream on laptops. Let chat model unload between turns if operator enabled unload-before-vision. Reduce attached image count. Close other GPU-heavy apps.

Cause: ARGUS disabled on server, audit running during stream, or VLM returned empty JSON.

Fix: Wait for chat stream to finish. Confirm local VLM installed. Retry with a clear UI screenshot. Check argus.enabled on server defaults. Engine → Logs for /api/argus/audit errors.

Cause: Preview worktree could not install dependencies within timeout.

Fix: Open sandbox worktree manually and fix npm ci / install errors. Increase argus.deps_install_timeout_sec on server if repo is large. Use paste audit path when sandbox bootstrap is not required.

Cause: You explicitly selected a cloud vision model in compose.

Fix: Select Local or Auto with local VLM installed. Attaching images alone should not force cloud — if it does, file a bug with support bundle and vision route from Lens.

Cause: lensPreviewEnabled off and first-N sends exhausted.

Fix: Enable contextmint.trust.lensPreviewEnabled. Toggle preview from compose or trust settings.

Cause: Pack not built or wrong name in manifest.

Fix: Packs panel → Scan & learn. Verify manifest.yaml name matches @pack reference.

Cause: Sources changed faster than auto-sync.

Fix: Rebuild pack. Enable autoSync with appropriate debounce. Commit pack sources if intentional.

Cause: Not in Agent mode, readiness blocked, or sandbox policy.

Fix: Switch to Agent mode. Confirm Ready/Limited/Indexing phase. Check sandbox.enabled settings.

Cause: File permissions, git conflict, or path outside workspace.

Fix: Review diff in patch preview. Ensure files writable. Use git to revert. Check Output for apply errors.

Cause: No quality scan run for workspace.

Fix: Engine → Quality → run scan. Wait for completion. Retry chat with governance preview enabled.

Cause: Server indexes /data/repos/foo but VS Code opens C:\foo.

Fix: Align paths via Remote SSH same absolute path or server-side path mapping. Re-register workspace on server.

Cause: Corporate MITM or self-signed cert not trusted.

Fix: Install org root CA on dev machine. Use valid internal cert on API ingress. Temporary dev-only: trust proxy settings per IT policy.

Cause: Embed batch + chat inference competing on same machine.

Fix: Let initial index complete. Use a smaller chat model. On contested shared Ollama hosts set server inline.pause_mode to shared_runtime (extension contextmint.inline.pauseWhileIndexing only tightens further). Schedule large reindex off-hours.

Cause: Many chunks retrieved before cap.

Fix: Narrow question. Attach specific files. Exclude irrelevant chunks in lens. Tune max context settings on server if operator.

1. Engine → About → export support bundle
2. Engine and extension version numbers
3. OS version and VS Code version
4. Steps to reproduce, readiness phase, context lane used
5. Relevant redacted log lines from Engine → Logs

Email anis@contextmint.ai or open GitHub issue for release builds.

Pilot cohorts get direct engineering channel. See Design Partners or your onboarding contact.