danny-avila/LibreChat · error · AgentRunEnvelopeError

${path} must be a non-empty string

Error message

${path} must be a non-empty string

What it means

assertNonEmptyString inside the agent-run envelope builder rejects any value that is not a string or is empty after trim. It guards principal.id (required), and principal.role / principal.tenantId when present. The thrown AgentRunEnvelopeError is a TypeError subclass, so it can be narrowed with instanceof.

Source

Thrown at packages/api/src/agents/envelope.ts:89

type CreateChatCompletionRunEnvelopeInput = Extract<
  CreateAgentRunEnvelopeInput,
  { protocol: 'chat.completions' }
>;
type CreateResponsesRunEnvelopeInput = Extract<
  CreateAgentRunEnvelopeInput,
  { protocol: 'responses' }
>;

export class AgentRunEnvelopeError extends TypeError {
  constructor(message: string) {
    super(message);
    this.name = 'AgentRunEnvelopeError';
  }
}

function assertNonEmptyString(value: string | undefined, path: string): string {
  if (typeof value !== 'string' || value.trim().length === 0) {
    throw new AgentRunEnvelopeError(`${path} must be a non-empty string`);
  }
  return value;
}

function cloneJsonValue<T>(value: T, path: string, ancestors: WeakSet<object>, depth: number): T;
function cloneJsonValue(
  value: unknown,
  path: string,
  ancestors: WeakSet<object>,
  depth: number,
): unknown {
  if (depth > AGENT_RUN_ENVELOPE_MAX_NESTING_DEPTH) {
    throw new AgentRunEnvelopeError(
      `${path} exceeds the maximum nesting depth of ${AGENT_RUN_ENVELOPE_MAX_NESTING_DEPTH}`,
    );
  }

  if (value === null || typeof value === 'string' || typeof value === 'boolean') {

View on GitHub (pinned to 5ff282f900)

Solutions

1. Ensure the request is authenticated and req.user.id is set before constructing the envelope.
2. Pass role/tenantId only when they are real strings; omit them otherwise (they are optional).
3. Catch AgentRunEnvelopeError specifically at the seam and return 401/400.

Example fix

// before
const envelope = createAgentRunEnvelope({
  protocol: 'chat.completions',
  requestId,
  receivedAt: Date.now(),
  principal: req.user, // id may be undefined
  payload,
});

// after
if (!req.user?.id) throw new Error('Authenticated user required');
const envelope = createAgentRunEnvelope({
  protocol: 'chat.completions',
  requestId,
  receivedAt: Date.now(),
  principal: { id: req.user.id, role: req.user.role, tenantId: req.user.tenantId },
  payload,
});

function assertNonEmptyString(v: unknown, path: string): string {
  if (typeof v !== 'string' || v.trim().length === 0) {
    throw new Error(`${path} must be a non-empty string`);
  }
  return v;
}
assertNonEmptyString(req.user?.id, 'principal.id');

const isNonEmptyString = (v: unknown): v is string =>
  typeof v === 'string' && v.trim().length > 0;

import { AgentRunEnvelopeError } from '~/agents/envelope';
try {
  envelope = createAgentRunEnvelope(input);
} catch (error) {
  if (error instanceof AgentRunEnvelopeError) {
    return res.status(400).json({ error: error.message });
  }
  throw error;
}

When it happens

Trigger: Calling createAgentRunEnvelope with principal.id undefined/null/''; passing principal.role as a number; a request where req.user.id was not populated upstream.

Common situations: An unauthenticated request reaching the envelope builder; a middleware order bug where req.user is not yet attached; passing a numeric role where a string is required; trimming an all-whitespace id.

Related errors

• ${path} exceeds the maximum nesting depth of ${AGENT_RUN_ENV
• ${path} must contain only finite numbers
• Invalid principal type: ${principalType}
• ${validation.error?.message}
• receivedAt must be a non-negative integer timestamp

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