{"record":{"id":"1c8a52fb3ee90834","repo":"danny-avila/LibreChat","slug":"receivedat-must-be-a-non-negative-integer-timestam","errorCode":null,"errorMessage":"receivedAt must be a non-negative integer timestamp","messagePattern":"receivedAt must be a non-negative integer timestamp","errorType":"validation","errorClass":"AgentRunEnvelopeError","httpStatus":null,"severity":"error","filePath":"packages/api/src/agents/envelope.ts","lineNumber":222,"sourceCode":"  return principal;\n}\n\n/**\n * Creates the versioned, transport-safe request that crosses the agent execution seam.\n * Runtime objects, provider clients, callbacks, credentials, and Express state belong to\n * the execution host and must never be added to this envelope.\n */\nexport function createAgentRunEnvelope(\n  input: CreateChatCompletionRunEnvelopeInput,\n): ChatCompletionRunEnvelope;\nexport function createAgentRunEnvelope(\n  input: CreateResponsesRunEnvelopeInput,\n): ResponsesRunEnvelope;\nexport function createAgentRunEnvelope(input: CreateAgentRunEnvelopeInput): AgentRunEnvelope {\n  const receivedProtocol: string = input.protocol;\n  const requestId = assertNonEmptyString(input.requestId, 'requestId');\n  if (!Number.isSafeInteger(input.receivedAt) || input.receivedAt < 0) {\n    throw new AgentRunEnvelopeError('receivedAt must be a non-negative integer timestamp');\n  }\n\n  const base = {\n    version: AGENT_RUN_ENVELOPE_VERSION,\n    requestId,\n    receivedAt: input.receivedAt,\n    principal: createPrincipal(input.principal),\n  };\n\n  if (input.protocol === 'chat.completions') {\n    return {\n      ...base,\n      protocol: input.protocol,\n      payload: cloneJsonValue(input.payload, 'payload', new WeakSet(), 0),\n    };\n  }\n\n  if (input.protocol === 'responses') {","sourceCodeStart":204,"sourceCodeEnd":240,"githubUrl":"https://github.com/danny-avila/LibreChat/blob/5ff282f9006c436e561de1afd39a481bea1ef0d8/packages/api/src/agents/envelope.ts#L204-L240","documentation":"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.","triggerScenarios":"Passing Date.now() as a string ('1234...'), a float (Date.now() + 0.5), NaN, Infinity, a negative number, a BigInt, or undefined for receivedAt.","commonSituations":"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.","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)."],"exampleFix":"// before\nconst env = createAgentRunEnvelope({ protocol, requestId, receivedAt: req.headers['x-timestamp'], principal, payload });\n\n// after\nconst receivedAt = Number(req.headers['x-timestamp']);\nif (!Number.isSafeInteger(receivedAt) || receivedAt < 0) throw new Error('bad timestamp');\nconst env = createAgentRunEnvelope({ protocol, requestId, receivedAt, principal, payload });","handlingStrategy":"validation","validationCode":"function asReceivedAt(raw: unknown): number {\n  const n = typeof raw === 'number' ? raw : Number(raw);\n  if (!Number.isSafeInteger(n) || n < 0) {\n    throw new Error(`receivedAt must be a non-negative safe integer, got: ${String(raw)}`);\n  }\n  return n;\n}\nconst env = createAgentRunEnvelope({ ...input, receivedAt: asReceivedAt(input.receivedAt) });","typeGuard":"function isNonNegSafeInt(value: unknown): value is number {\n  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;\n}","tryCatchPattern":"try {\n  const env = createAgentRunEnvelope(input);\n} catch (e) {\n  if (e instanceof AgentRunEnvelopeError && /receivedAt/.test(e.message)) {\n    input.receivedAt = Date.now(); // fall back to current epoch-millis\n    // then retry\n  } else throw e;\n}","preventionTips":["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."],"tags":["timestamp","validation","agent-envelope","input-validation","typescript"],"backgroundTag":null,"analyzedSha":"5ff282f9006c436e561de1afd39a481bea1ef0d8","analyzedAt":"2026-08-12T21:38:08.145Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}