danny-avila/LibreChat · error

No agent ID provided for agent file upload

Error message

No agent ID provided for agent file upload

What it means

Thrown when there is no `agent_id` and the upload is not a `messageAttachment` (metadata.message_file). The contract is mutually exclusive: an agent upload needs an agent_id, OR the upload must be flagged as a chat message attachment. Without either, the server has no entity to bind the file to.

Source

Thrown at api/server/services/Files/process.js:686

 * @returns {Promise<void>}
 */
const processAgentFileUpload = async ({ req, res, metadata, sseStream }) => {
  const { file } = req;
  const appConfig = req.config;
  const { agent_id, tool_resource, file_id, temp_file_id = null } = metadata;

  let messageAttachment = !!metadata.message_file;

  if (agent_id && !tool_resource && !messageAttachment) {
    throw new Error('No tool resource provided for agent file upload');
  }

  if (tool_resource === EToolResources.file_search && file.mimetype.startsWith('image')) {
    throw new Error('Image uploads are not supported for file search tool resources');
  }

  if (!messageAttachment && !agent_id) {
    throw new Error('No agent ID provided for agent file upload');
  }

  const isImage = file.mimetype.startsWith('image');
  let fileInfoMetadata;
  const entity_id = messageAttachment === true ? undefined : agent_id;
  const basePath = mime.getType(file.originalname)?.startsWith('image') ? 'images' : 'uploads';
  if (tool_resource === EToolResources.execute_code) {
    const isCodeEnabled = await checkCapability(req, AgentCapabilities.execute_code);
    if (!isCodeEnabled) {
      throw new Error('Code execution is not enabled for Agents');
    }
    const { handleFileUpload: uploadCodeEnvFile } = getStrategyFunctions(FileSources.execute_code);
    const stream = fs.createReadStream(file.path);
    /* Resource identity for codeapi's sessionKey:
     * - chat attachments (messageAttachment=true): `kind: 'user'`, codeapi
     *   buckets under `<tenant>:user:<authContext.userId>` regardless of `id`.
     * - agent setup files (messageAttachment=false): `kind: 'agent'`, shared
     *   per agent identity. `id` carries the agent id. */

View on GitHub (pinned to 5ff282f900)

Solutions

1. Provide `agent_id` in metadata when uploading to an agent.
2. Or set `message_file: true` to upload as a chat attachment bound to the user.
3. Validate client-side: `if (!agent_id && !message_file) return error;` before submit.
4. If you reached this branch unexpectedly, log the metadata payload — a field is missing upstream.

Example fix

// before
metadata: { tool_resource: 'file_search' }

// after
metadata: { agent_id: req.body.agent_id, tool_resource: 'file_search' }

function validateAgentUploadMetadata(metadata) {
  const { agent_id, message_file } = metadata;
  if (!agent_id && !message_file) {
    return 'Either agent_id or message_file must be provided';
  }
  return null;
}

try { await processAgentFileUpload({ req, res, metadata }); }
catch (e) {
  if (/No agent ID provided/.test(e.message)) return res.status(400).json({ error: e.message });
  throw e;
}

When it happens

Trigger: POST to the agent file upload endpoint with metadata that omits both `agent_id` and `message_file`. Common when a generic upload call is reused without context, or a frontend drops the agent_id field when no agent is selected.

Common situations: Client integration calling the endpoint without agent context; a frontend bug where the agent_id form field is conditionally rendered and absent; a malformed curl/test script.

Related errors

• No tool resource provided for agent file upload
• Image uploads are not supported for file search tool resourc
• [${req.baseUrl}] Endpoint is required
• Storage backend "${source}" does not support file writes
• Authentication failed: ${error.message}

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