Troubleshooting

Relevant source files

The following files were used as context for generating this wiki page:

• cmd/app/main.go
• setup-ollama.md
• internal/search/service.go
• internal/qdrant/client.go
• internal/embeddings/ollama.go
• internal/embeddings/openai.go

This document provides guidance for diagnosing and resolving common issues within the MauQNotes application. It covers problems related to configuration, external service connectivity (Ollama, Qdrant), and the core data processing workflows for ingestion and querying. Understanding these components is key to ensuring the semantic search functionality operates correctly.

The primary failure points often involve incorrect environment variable settings, network issues preventing connection to dependent services, or mismatches between embedding model dimensions and the vector database configuration. The application will terminate with a fatal error message, such as ingest failed or search failed, which indicates a problem in one of these areas.

Sources: cmd/app/main.go:17-26

Common Failure Points

1. Configuration Errors

Incorrect or missing environment variables are a primary source of errors. The application uses a .env file to load configuration for its dependencies.

Sources: internal/search/service.go:11, internal/qdrant/client.go:73, internal/embeddings/ollama.go:23, internal/embeddings/openai.go:25

The following table summarizes the key environment variables:

Variable	Service	Description	Default Value	Source File
QDRANT_URL	Qdrant	The base URL for the Qdrant instance. Must start with http:// or https://.	(none)	internal/qdrant/client.go:75
QDRANT_API_KEY	Qdrant	The API key for authenticating with Qdrant. Optional.	(none)	internal/qdrant/client.go:76
QDRANT_COLLECTION	Qdrant	The name of the collection to use in Qdrant.	(none)	internal/qdrant/client.go:77
OLLAMA_URL	Ollama	The URL for the Ollama service API.	http://localhost:11434	internal/embeddings/ollama.go:25-28
EMBEDDING_MODEL	Ollama / OpenAI	The name of the embedding model to use.	nomic-embed-text	internal/embeddings/ollama.go:33, internal/search/service.go:13
OPENAI_API_KEY	OpenAI	The API key for OpenAI services. Required if using an OpenAI model.	(none)	internal/embeddings/openai.go:26

A validate() function in the Qdrant client checks for QDRANT_URL and QDRANT_COLLECTION. If either is missing, the application will fail with an error.

Sources: internal/qdrant/client.go:81-90

2. External Service Connectivity

The application relies on two external services: Ollama for generating embeddings and Qdrant as the vector database.

Ollama Connectivity

The application connects to Ollama to generate vector embeddings from text.

• URL: The connection is made to the URL specified in OLLAMA_URL, which defaults to http://localhost:11434.
• Endpoint: The specific endpoint used is /api/embeddings.
• Failure: A connection failure to this service will prevent both ingestion and querying, typically resulting in an error from the http.DefaultClient.

Sources: internal/embeddings/ollama.go:26-28, internal/embeddings/ollama.go:44-47, setup-ollama.md:16

Qdrant Connectivity

The Qdrant client communicates with the vector database for all storage and retrieval operations.

• URL: The client uses the QDRANT_URL environment variable.
• Validation: The URL must be set and begin with http:// or https://.
• Authentication: If QDRANT_API_KEY is set, it will be included as an api-key header in all requests.
• Failure: Errors during CreateCollectionIfNotExists, Upsert, or Search will be returned. The Upsert function provides a detailed error message from the Qdrant response body if the operation fails.

Sources: internal/qdrant/client.go:81-90, internal/qdrant/client.go:92-97, internal/qdrant/client.go:132-136

3. Model and Dimension Mismatch

A critical error occurs if the vector dimension of the embedding model does not match the dimension configured for the Qdrant collection. The application determines the dimension based on the EMBEDDING_MODEL environment variable.

The following diagram shows the logic for determining the vector dimension.

This diagram illustrates how the Init function in the search service maps a model name to a specific vector dimension.
Sources: internal/search/service.go:12-29

The following table lists the models and their corresponding dimensions as configured in the application:

Model Name	Vector Dimension	Source File
nomic-embed-text	768	internal/search/service.go:22
all-minilm	384	internal/search/service.go:24
mxbai-embed-large	512	internal/search/service.go:26

Note: There is a discrepancy for mxbai-embed-large. The application code sets its dimension to 512, while the documentation suggests 1024. The application will use 512 when creating the collection. Using a model that produces 1024 dimensions will cause an error during the upsert operation in Qdrant.

Sources: internal/search/service.go:26, setup-ollama.md:21

Data Flow Failures

Errors can occur during the two main application flows: ingestion and querying.

Ingestion Flow (IngestNotes)

The ingestion process involves generating embeddings for notes and storing them in Qdrant. An error at any step will cause the main function to log an "ingest failed" message and exit.

Sources: cmd/app/main.go:17-19

The sequence diagram below shows the interactions during ingestion.

This diagram shows the sequence of calls starting from main.go through the search service, embedding generation, and finally to the Qdrant client for storing the data.
Sources: internal/search/service.go:32-58, cmd/app/main.go:17

Query Flow (Query)

The query process generates an embedding for a search query and uses it to find similar notes in Qdrant. An error here will cause the main function to log a "search failed" message and exit.

Sources: cmd/app/main.go:23-26

The sequence diagram below shows the interactions during a query.

This diagram illustrates the query workflow, where a query is converted into a vector and sent to Qdrant to find the most relevant results.
Sources: internal/search/service.go:60-68, cmd/app/main.go:23

OpenAI Embedding Provider (Alternative)

The codebase includes a client for generating embeddings via the OpenAI API, but it is not used by the primary search.service. To use it, the search.service would need to be modified to call embeddings.FromOpenAI instead of embeddings.FromOllama.

Troubleshooting for this provider would involve:

1. Ensuring OPENAI_API_KEY and EMBEDDING_MODEL are set in the environment.
2. Verifying network connectivity to https://api.openai.com/v1/embeddings.
3. Confirming the chosen model name is valid for the OpenAI API.

Sources: internal/embeddings/openai.go

Summary

To troubleshoot MauQNotes effectively, follow these steps:

1. Check Environment Variables: Verify that all required variables in your .env file are correct, especially QDRANT_URL, QDRANT_COLLECTION, and EMBEDDING_MODEL.
2. Verify Service Connectivity: Ensure the application can reach both the Qdrant instance at QDRANT_URL and the Ollama service at OLLAMA_URL.
3. Confirm Model and Dimension Alignment: Make sure the EMBEDDING_MODEL you are using corresponds to the vector dimension expected by the application and configured in your Qdrant collection.
4. Trace Application Logs: Look for fatal error messages like "ingest failed" or "search failed" and the more detailed errors that precede them, which often point to the exact Qdrant or HTTP client failure.

Sources: cmd/app/main.go:18,25, internal/qdrant/client.go:83,89,111,135, internal/embeddings/ollama.go:55