What causes "receivedAt must be a non-negative integer timestamp" in danny-avila/LibreChat?

Use Number.isSafeInteger(Date.now()) && Date.now() >= 0 — always pass Date.now() directly (a number).

danny-avila/LibreChat · error · AgentRunEnvelopeError

receivedAt must be a non-negative integer timestamp

Error message

receivedAt must be a non-negative integer timestamp

What it means

Thrown by createAgentRunEnvelope when input.receivedAt is not a safe non-negative integer. Number.isSafeInteger must be true and the value must be >= 0. receivedAt is the envelope's receipt timestamp and must be an exact integer epoch-millis so the envelope stays deterministic across the transport seam.

Source

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

  return principal;
}

/**
 * Creates the versioned, transport-safe request that crosses the agent execution seam.
 * Runtime objects, provider clients, callbacks, credentials, and Express state belong to
 * the execution host and must never be added to this envelope.
 */
export function createAgentRunEnvelope(
  input: CreateChatCompletionRunEnvelopeInput,
): ChatCompletionRunEnvelope;
export function createAgentRunEnvelope(
  input: CreateResponsesRunEnvelopeInput,
): ResponsesRunEnvelope;
export function createAgentRunEnvelope(input: CreateAgentRunEnvelopeInput): AgentRunEnvelope {
  const receivedProtocol: string = input.protocol;
  const requestId = assertNonEmptyString(input.requestId, 'requestId');
  if (!Number.isSafeInteger(input.receivedAt) || input.receivedAt < 0) {
    throw new AgentRunEnvelopeError('receivedAt must be a non-negative integer timestamp');
  }

  const base = {
    version: AGENT_RUN_ENVELOPE_VERSION,
    requestId,
    receivedAt: input.receivedAt,
    principal: createPrincipal(input.principal),
  };

  if (input.protocol === 'chat.completions') {
    return {
      ...base,
      protocol: input.protocol,
      payload: cloneJsonValue(input.payload, 'payload', new WeakSet(), 0),
    };
  }

  if (input.protocol === 'responses') {

View on GitHub (pinned to 5ff282f900)

Solutions

Use Number.isSafeInteger(Date.now()) && Date.now() >= 0 — always pass Date.now() directly (a number).
If the value comes from a string source, coerce and validate: const t = Number(raw); if (!Number.isSafeInteger(t) || t < 0) throw.
Ensure you pass epoch milliseconds, not seconds (multiply seconds by 1000).

Example fix

// before
const env = createAgentRunEnvelope({ protocol, requestId, receivedAt: req.headers['x-timestamp'], principal, payload });

// after
const receivedAt = Number(req.headers['x-timestamp']);
if (!Number.isSafeInteger(receivedAt) || receivedAt < 0) throw new Error('bad timestamp');
const env = createAgentRunEnvelope({ protocol, requestId, receivedAt, principal, payload });

Defensive patterns

Strategy: validation

Validate before calling

function asReceivedAt(raw: unknown): number {
  const n = typeof raw === 'number' ? raw : Number(raw);
  if (!Number.isSafeInteger(n) || n < 0) {
    throw new Error(`receivedAt must be a non-negative safe integer, got: ${String(raw)}`);
  }
  return n;
}
const env = createAgentRunEnvelope({ ...input, receivedAt: asReceivedAt(input.receivedAt) });

Type guard

function isNonNegSafeInt(value: unknown): value is number {
  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
}

Try / catch

try {
  const env = createAgentRunEnvelope(input);
} catch (e) {
  if (e instanceof AgentRunEnvelopeError && /receivedAt/.test(e.message)) {
    input.receivedAt = Date.now(); // fall back to current epoch-millis
    // then retry
  } else throw e;
}

Prevention

Always pass Date.now() (a number) directly; do not stringify timestamps.
When reading timestamps from headers/env/config, coerce with Number() and validate first.
Use epoch milliseconds consistently; never seconds.

When it happens

Trigger: Passing Date.now() as a string ('1234...'), a float (Date.now() + 0.5), NaN, Infinity, a negative number, a BigInt, or undefined for receivedAt.

Common situations: Reading the timestamp from an env var or header (string) without Number(); mixing seconds and milliseconds; client clocks producing fractional timestamps; passing a Date object instead of its getTime() value.

Related errors

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