Troubleshooting

Executive summary

This guide is for fast recovery when Conduit doesn't work. Debug from the outside in: system -> Conduit -> KB -> MCP -> AI client. Most issues are dependency, runtime, or index state problems rather than core logic bugs. For setup and basics, see /docs/install, /docs/quickstart, /docs/admin, and /docs/mcp.

Before you start (2-minute reset)

• Check your Conduit version: conduit --version.
• Confirm container runtime installed: Podman preferred, Docker supported.
• Confirm Qdrant reachable: conduit qdrant status.
• If using KAG, confirm FalkorDB: conduit falkordb status.
• Confirm Conduit is responsive: conduit status and conduit doctor.

If anything fails, fix the earlier step before moving on.

The debugging order (don't skip steps)

1. Installation sanity

   • Good: conduit --version works and conduit status responds.
   • Failures: command not found, permission denied.
   • Next action: verify PATH, reinstall via the installer if needed.

2. Runtime + DB dependencies

   • Good: Podman/Docker, Qdrant, and Ollama are running.
   • Failures: connection refused to Qdrant, container runtime errors.
   • Next action: conduit qdrant stop then conduit qdrant start; ensure runtime is running.

3. Conduit configuration + state

   • Good: conduit doctor shows healthy checks.
   • Failures: daemon not running, socket missing.
   • Next action: conduit service start and re-check.

4. KB ingestion + sync (RAG)

   • Good: conduit kb sync succeeds and conduit kb search returns results.
   • Failures: sync completes but search returns nothing.
   • Next action: verify sources with conduit kb list, re-sync, rebuild vectors if needed.

5. Optional KAG build

   • Good: conduit kb kag-sync completes and conduit kb kag-status shows progress.
   • Failures: empty results, very slow extraction.
   • Next action: ensure KAG is enabled and dependencies are healthy; consider limiting scope with --source.

6. MCP server artifact exists

   • Good: conduit mcp status shows MCP ready.
   • Failures: MCP not listed, client does not see tools.
   • Next action: re-run conduit mcp configure, verify config path with conduit client list.

7. AI tool wiring + permissions

   • Good: client lists the MCP server.
   • Failures: server listed but tool calls fail.
   • Next action: check config path, restart client, verify PATH and env vars.

8. Query test and interpretation

   • Good: tool returns snippets and citations.
   • Failures: irrelevant answers or empty results.
   • Next action: re-sync KB, validate source coverage, adjust queries.

Quick triage table (symptom -> likely cause -> fastest fix)

Troubleshooting by layer

1) Installation & environment

• Verify conduit --version and conduit status.
• If the CLI is missing, reinstall with the installer script from the repo README.
• Avoid deleting ~/.conduit/ unless you intend to lose local state.

2) Container runtime: Podman / Docker

• Check dependency status: conduit deps status.
• Podman is preferred for rootless isolation; Docker is supported.
• If the runtime is down, start it and re-run conduit doctor.

3) Qdrant (RAG vectors)

• Check: conduit qdrant status and conduit status.
• If vectors are 0, rebuild: conduit kb sync --rebuild-vectors.
• If Qdrant is stopped, restart it:

conduit qdrant stop
conduit qdrant start

4) FalkorDB (KAG graph, optional)

• Only required for multi-hop graph traversal.
• Check: conduit falkordb status.
• Restart if needed:

conduit falkordb stop
conduit falkordb start

• If you do not need KAG, keep it disabled and focus on RAG.

5) Conduit KB: sources, sync, and search

conduit kb list
conduit kb add <path>
conduit kb sync
conduit kb search "authentication"

If results are empty:

• Verify the source path exists.
• Re-sync with conduit kb sync --rebuild-vectors if semantic search is broken.

6) MCP integration layer

• Check readiness: conduit mcp status.
• Reconfigure client: conduit mcp configure.
• Verify config paths: conduit client list.

See /docs/mcp for client wiring details.

7) AI client wiring issues

• Confirm the MCP server entry exists in the client config file.
• Restart the client after edits.
• Run a minimal test prompt: "Search my KB for authentication and cite sources." If no results, go back to KB sync.

Performance & stability notes

• Slow sync is usually document volume + embeddings. Start with a smaller dataset and expand.
• KAG extraction is slower than vector indexing; it can take seconds per chunk depending on provider.
• Cold starts can be slow; warming Ollama helps: conduit ollama warmup.

Known issues (curated)

Known issues doc: https://github.com/amlandas/Conduit-AI-Intelligence-Hub/blob/main/docs/KNOWN_ISSUES.md

When to reset vs. when to reinstall

• Reset vectors when semantic search is broken: conduit kb sync --rebuild-vectors.
• Remove and re-add a source if only one source is problematic.
• Reinstall the CLI only if the binary is corrupted or missing.
• Avoid deleting ~/.conduit/ unless you intend to lose KB data.

How to report a bug (so maintainers can help quickly)

File issues here: https://github.com/amlandas/Conduit-AI-Intelligence-Hub/issues

Include:

• OS and version
• Conduit version (conduit --version)
• Container runtime version
• Qdrant/FalkorDB status
• Commands run and exact errors
• Logs from ~/.conduit/logs/ or ~/Library/Logs/conduit/
• Minimal reproduction steps