errors

errors.py

User-friendly error classification — maps raw Python exceptions to actionable messages that users can understand. Used by both REST API and MCP server.

---

Key Concepts

Term	Definition	Example
embedding	A numerical vector (list of numbers) that represents the meaning of text. Similar text → similar vectors.	The code def add(a, b): return a+b might become [0.12, -0.45, 0.78, ...] (1536 numbers for OpenAI).
ChromaDB	An open-source vector database for storing and searching embeddings. Used here to store code chunks.	collection.query(query_texts=["scan files"], n_results=5) returns the 5 closest code chunks.
LLM	Large Language Model — an AI model (like GPT-4, Claude) that generates text given a prompt.	get_llm() returns a ChatOpenAI instance that can answer questions about code.

---

Class: CodewalkError

One-line: Base exception with a user_message field for display and an optional detail field.

Example: Creating a CodewalkError

Input: user_message="No codebase analyzed yet.", detail="collection 'codebase' not found"

Line 10: self.user_message = "No codebase analyzed yet."
Line 11: self.detail = "collection 'codebase' not found"
Line 12: super().__init__("No codebase analyzed yet.")

Result: CodewalkError with .user_message = "No codebase analyzed yet.", .detail = "collection 'codebase' not found", str(error) = "No codebase analyzed yet."

---

Constant: _ERROR_PATTERNS

One-line: List of (substring, user_friendly_message) tuples that maps known error substrings to helpful messages.

Patterns (13 total):

Pattern Substring	User Message
"No codebase indexed"	"No codebase analyzed yet. Run the analyze endpoint first..."
"Connection refused"	"Can't reach the LLM. If using Ollama, run ollama serve..."
"api_key"	"API key not set or invalid..."
"RateLimitError"	"Rate limit hit. Wait a moment and try again..."
"model_not_found"	"LLM model not found. If using Ollama, run ollama pull..."
"embedding"	"Embedding model error..."
"chromadb"	"Vector database error. Try deleting .codewalk/chroma/..."
"microphone"	"Microphone access denied..."

---

Function: classify_error(exception)

One-line: Converts a raw exception to a user-friendly error string by matching against _ERROR_PATTERNS.

Example: Connection refused error

Input: exception = ConnectionError("Connection refused to localhost:11434")

Line 80: error_str = str(exception).lower()
         → error_str = "connection refused to localhost:11434"

Line 81: error_type = type(exception).__name__.lower()
         → error_type = "connectionerror"

Line 83: Loop through _ERROR_PATTERNS:
  - pattern = "No codebase indexed" → "no codebase indexed" in "connection refused to localhost:11434"? No
  - pattern = "No analysis data" → No
  - pattern = "collection" → "collection" in "connection refused to localhost:11434"? No
  - pattern = "Connection refused" → "connection refused" in "connection refused to localhost:11434"? YES
  
Line 85: return "Can't reach the LLM. If using Ollama, run `ollama serve`. If using OpenAI/Anthropic, check your API key."

Return: "Can't reach the LLM. If using Ollama, run 'ollama serve'. If using OpenAI/Anthropic, check your API key."

Example: Unknown error (fallback)

Input: exception = RuntimeError("Something weird happened")

Line 80: error_str = "something weird happened"
Line 81: error_type = "runtimeerror"
Line 83: Loop through all 13 patterns → none match
Line 88: return "Something went wrong: Something weird happened"

Return: "Something went wrong: Something weird happened"