Error Handling
Errors are an expected part of any AI application.
A Ragfish application can interact with multiple components, including AI providers, vector stores, connectors, document processors, and external services. Failures can therefore occur at different stages of the application lifecycle.
Ragfish provides a consistent framework architecture so that applications can identify and handle these failures appropriately.
Where Errors Can Occur
A typical Ragfish request can pass through several components:
User Request
│
▼
Chat
│
▼
Retriever
│
▼
Vector Store
│
▼
AI Provider
│
▼
Response
An error can occur at any of these stages.
For example:
Invalid configuration
Missing API credentials
AI provider failure
Vector store connection failure
Retrieval failure
Invalid input
Document ingestion failure
Network failure
Error Handling Philosophy
Ragfish follows a modular architecture, so errors should be handled at the appropriate layer.
Application
│
▼
Ragfish Core
│
┌───────────────┼───────────────┐
▼ ▼ ▼
LLM Retriever Connector
│ │ │
▼ ▼ ▼
Provider Vector DB Source
The application should distinguish between:
Errors that can be corrected by the user.
Errors that require configuration changes.
Temporary external-service failures.
Programming or implementation errors.
Configuration Errors
Configuration errors commonly occur when required settings are missing or invalid.
For example, an AI provider may require an API key:
Settings.llm = new OpenAILLM({
apiKey: process.env.OPENAI_API_KEY
});
If the required environment variable is missing, the application should identify the configuration problem before attempting to process user requests.
A recommended startup check is:
if (!process.env.OPENAI_API_KEY) {
throw new Error("OPENAI_API_KEY is not configured");
}
This allows configuration problems to be detected early.
AI Provider Errors
AI provider requests depend on external services.
Possible failures include:
Invalid credentials
Rate limits
Network failures
Provider outages
Invalid model configuration
Request limits
Your application should handle provider failures gracefully rather than exposing internal errors directly to end users.
For example:
try {
const response = await chat.message(
"What is Ragfish?"
);
console.log(response);
} catch (error) {
console.error("AI request failed:", error);
}
The exact error types available depend on the provider package being used.
Vector Store Errors
Retrieval depends on the configured vector store.
For example, a Qdrant-based application may fail if the vector database is unavailable.
const vectorStore = new QdrantVectorStore({
url: process.env.QDRANT_URL,
apiKey: process.env.QDRANT_API_KEY
});
Possible failures include:
Invalid connection details
Authentication failure
Collection not found
Network failure
Search failure
Service unavailable
These errors should be handled separately from AI provider errors because the appropriate recovery strategy may be different.
Retrieval Errors
A retrieval operation can fail even when the language model is available.
For example:
User Question
│
▼
Retriever
│
X
│
Retrieval Error
Applications should avoid silently generating an answer when the required knowledge could not be retrieved.
Depending on the application, you may choose to:
Retry the retrieval operation.
Return a clear error.
Ask the user to try again.
Fall back to another retrieval strategy.
Log the failure for investigation.
Ingestion Errors
Errors can also occur while importing knowledge.
For example:
Knowledge Source
│
▼
Ingestion
│
X
│
Ingestion Error
Common causes include:
Unsupported files
Invalid document content
Corrupted files
Missing permissions
Connector failures
External service errors
For large ingestion jobs, it is often better to isolate failed items rather than allowing one failed document to stop the entire process.
Input Validation
Applications should validate user input before sending it through the Ragfish pipeline.
For example:
const question = input.trim();
if (!question) {
throw new Error("Question cannot be empty");
}
const response = await chat.message(question);
Input validation helps prevent unnecessary model and retrieval requests.
Handling Errors at Application Boundaries
Errors should generally be handled at the application boundary.
For example, in an API application:
HTTP Request
│
▼
Application Route
│
▼
Ragfish
│
X
│
Error
│
▼
Application Error Handler
│
▼
Safe API Response
Internal error details should be logged for developers but should not necessarily be exposed directly to end users.
Logging
Logging is important when diagnosing failures in production.
A useful error log should contain enough context to identify the failed operation.
For example:
try {
const response = await chat.message(question);
return response;
} catch (error) {
console.error("Chat request failed", {
error,
question
});
throw error;
}
Avoid logging sensitive information such as API keys, passwords, or confidential document content.
Retry Strategies
Some failures are temporary.
For example:
Request │ ▼ Provider │ X Temporary Failure │ ▼ Retry │ ▼ Success
Retries can be useful for transient network or service failures.
However, retries should be used carefully. Repeatedly retrying permanent failures can increase latency and unnecessary costs.
Consider:
Maximum retry attempts
Retry delays
Exponential backoff
Which errors are safe to retry
Graceful Failure
AI applications should fail gracefully.
Instead of returning an internal exception directly to the user:
Internal vector database connection error:
ECONNREFUSED...
the application can provide a safe message:
We couldn't retrieve the requested information.
Please try again shortly.
The detailed error can remain in the application logs for troubleshooting.
Error Handling by Layer
A useful way to organize error handling is by framework layer.
Layer
Example Failure
Typical Response
Configuration
Missing API key
Fix configuration
Connector
Source unavailable
Retry or report source failure
Ingestion
Invalid document
Skip or report failed item
Chunking
Invalid content
Validate or reject input
Retrieval
Vector store unavailable
Retry or fail gracefully
LLM
Provider error
Retry when appropriate
Application
Invalid user input
Validate and return a safe error
Development vs Production
Error handling requirements are different during development and production.
Development
During development, detailed errors are useful for debugging.
console.error(error);
Production
In production:
Log detailed technical information.
Return safe user-facing messages.
Avoid exposing credentials or internal infrastructure.
Track recurring failures.
Monitor external service availability.
Best Practices
When handling errors in Ragfish applications:
Validate configuration during startup.
Validate user input before processing.
Handle external provider failures explicitly.
Separate retrieval failures from LLM failures.
Log useful diagnostic information.
Never expose API keys or sensitive information.
Retry only errors that are likely to be temporary.
Use safe user-facing error messages.
Monitor recurring production failures.
Core Framework Complete
You have now completed the core concepts of the Ragfish Framework:
Overview ↓ Architecture ↓ Settings ↓ Assistant ↓ Chat ↓ Ingestion ↓ Chunking ↓ Retrieval ↓ Interfaces ↓ Types ↓ Error Handling
You now have the foundation required to understand how Ragfish applications are structured and how the major framework components work together.
What's Next?
The next section of the documentation focuses on AI Providers.
Continue to AI Providers → Overview to learn how Ragfish integrates language models and embedding providers through its modular provider architecture.