danny-avila/LibreChat · critical

RAG_API_URL not defined

Error message

RAG_API_URL not defined

What it means

Thrown by uploadVectors at the very start of the function when process.env.RAG_API_URL is falsy. This is a hard configuration gate: without the RAG API URL, the function cannot POST embeddings. Unlike deleteVectors (which silently returns if RAG_API_URL is unset), uploadVectors throws because there is no silent fallback for a failed upload — the caller must know the upload did not happen.

Source

Thrown at api/server/services/Files/VectorDB/crud.js:69

/**
 * Uploads a file to the configured Vector database
 *
 * @param {Object} params - The params object.
 * @param {Object} params.req - The request object from Express. It should have a `user` property with an `id` representing the user
 * @param {Express.Multer.File} params.file - The file object, which is part of the request. The file object should
 *                                     have a `path` property that points to the location of the uploaded file.
 * @param {string} params.file_id - The file ID.
 * @param {string} [params.entity_id] - The entity ID for shared resources.
 * @param {Object} [params.storageMetadata] - Storage metadata for dual storage pattern.
 *
 * @returns {Promise<{ filepath: string, bytes: number }>}
 *          A promise that resolves to an object containing:
 *            - filepath: The path where the file is saved.
 *            - bytes: The size of the file in bytes.
 */
async function uploadVectors({ req, file, file_id, entity_id, storageMetadata }) {
  if (!process.env.RAG_API_URL) {
    throw new Error('RAG_API_URL not defined');
  }

  try {
    const jwtToken = generateShortLivedToken(req.user.id);
    const formData = new FormData();
    formData.append('file_id', file_id);
    formData.append('file', fs.createReadStream(file.path));
    if (entity_id != null && entity_id) {
      formData.append('entity_id', entity_id);
    }

    // Include storage metadata for RAG API to store with embeddings
    if (storageMetadata) {
      formData.append('storage_metadata', JSON.stringify(storageMetadata));
    }

    const formHeaders = formData.getHeaders();

View on GitHub (pinned to 5ff282f900)

Solutions

1. Set RAG_API_URL in your .env file to the base URL of your RAG API service (e.g., http://rag-api:8000).
2. If RAG features are not desired, disable the vector database storage option in the application configuration so uploadVectors is never called.
3. Verify the variable name matches exactly (case-sensitive) and that the .env file is loaded before the server starts.
4. Add a startup check that warns or errors if RAG_API_URL is unset when vector storage is configured.

Example fix

# .env
RAG_API_URL=http://rag-api:8000

if (!process.env.RAG_API_URL) {
  throw new Error('RAG_API_URL is not set. Configure it in .env or disable vector storage.');
}

function isRagConfigured(): boolean {
  return Boolean(process.env.RAG_API_URL);
}

try {
  await uploadVectors({ req, file, file_id });
} catch (error) {
  if (error.message === 'RAG_API_URL not defined') {
    return res.status(503).json({ error: 'Vector storage is not configured' });
  }
  throw error;
}

When it happens

Trigger: Calling uploadVectors({ req, file, file_id }) when the RAG_API_URL environment variable is not set or is empty. This triggers before any network request is attempted.

Common situations: RAG/vector database features are enabled in the application configuration but RAG_API_URL was not added to .env. Or the environment variable was misspelled (e.g., RAG_API_URL vs RAGAPI_URL). Or the variable was set in a different environment (e.g., development) but not in production.

Related errors

• File embedding failed. The filetype ${file.mimetype} is not
• File embedding failed.
• An error occurred during file upload.
• Storage backend "${source}" does not support file writes
• An error occurred during file deletion.

AI-assisted analysis of danny-avila/LibreChat@5ff282f900 (2026-08-12). Data as JSON: /api/errors/3d2ed9bfdab75f4c. Report an issue: GitHub.