{"record":{"id":"3d2ed9bfdab75f4c","repo":"danny-avila/LibreChat","slug":"rag-api-url-not-defined","errorCode":null,"errorMessage":"RAG_API_URL not defined","messagePattern":"RAG_API_URL not defined","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"api/server/services/Files/VectorDB/crud.js","lineNumber":69,"sourceCode":"/**\n * Uploads a file to the configured Vector database\n *\n * @param {Object} params - The params object.\n * @param {Object} params.req - The request object from Express. It should have a `user` property with an `id` representing the user\n * @param {Express.Multer.File} params.file - The file object, which is part of the request. The file object should\n *                                     have a `path` property that points to the location of the uploaded file.\n * @param {string} params.file_id - The file ID.\n * @param {string} [params.entity_id] - The entity ID for shared resources.\n * @param {Object} [params.storageMetadata] - Storage metadata for dual storage pattern.\n *\n * @returns {Promise<{ filepath: string, bytes: number }>}\n *          A promise that resolves to an object containing:\n *            - filepath: The path where the file is saved.\n *            - bytes: The size of the file in bytes.\n */\nasync function uploadVectors({ req, file, file_id, entity_id, storageMetadata }) {\n  if (!process.env.RAG_API_URL) {\n    throw new Error('RAG_API_URL not defined');\n  }\n\n  try {\n    const jwtToken = generateShortLivedToken(req.user.id);\n    const formData = new FormData();\n    formData.append('file_id', file_id);\n    formData.append('file', fs.createReadStream(file.path));\n    if (entity_id != null && entity_id) {\n      formData.append('entity_id', entity_id);\n    }\n\n    // Include storage metadata for RAG API to store with embeddings\n    if (storageMetadata) {\n      formData.append('storage_metadata', JSON.stringify(storageMetadata));\n    }\n\n    const formHeaders = formData.getHeaders();\n","sourceCodeStart":51,"sourceCodeEnd":87,"githubUrl":"https://github.com/danny-avila/LibreChat/blob/5ff282f9006c436e561de1afd39a481bea1ef0d8/api/server/services/Files/VectorDB/crud.js#L51-L87","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set RAG_API_URL in your .env file to the base URL of your RAG API service (e.g., http://rag-api:8000).","If RAG features are not desired, disable the vector database storage option in the application configuration so uploadVectors is never called.","Verify the variable name matches exactly (case-sensitive) and that the .env file is loaded before the server starts.","Add a startup check that warns or errors if RAG_API_URL is unset when vector storage is configured."],"exampleFix":"# .env\nRAG_API_URL=http://rag-api:8000","handlingStrategy":"validation","validationCode":"if (!process.env.RAG_API_URL) {\n  throw new Error('RAG_API_URL is not set. Configure it in .env or disable vector storage.');\n}","typeGuard":"function isRagConfigured(): boolean {\n  return Boolean(process.env.RAG_API_URL);\n}","tryCatchPattern":"try {\n  await uploadVectors({ req, file, file_id });\n} catch (error) {\n  if (error.message === 'RAG_API_URL not defined') {\n    return res.status(503).json({ error: 'Vector storage is not configured' });\n  }\n  throw error;\n}","preventionTips":["Set RAG_API_URL in .env when vector/RAG features are enabled.","Add a startup check that verifies RAG_API_URL is set when vector storage is configured.","Disable vector storage routing if RAG is not deployed to avoid calling uploadVectors."],"tags":["vectordb","rag","configuration","environment-variables","file-upload"],"backgroundTag":null,"analyzedSha":"5ff282f9006c436e561de1afd39a481bea1ef0d8","analyzedAt":"2026-08-12T21:38:08.145Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}