Hmbown/CodeWhale · error · Error

payload exceeds bytes

Error message

payload exceeds ${MAX_PAYLOAD_BYTES} bytes

What it means

buildEnvelope canonicalizes the payload to JSON bytes and enforces MAX_PAYLOAD_BYTES before signing. This error means the canonicalized payload is larger than the repository's published size budget, so the envelope is refused rather than signed and shipped. The limit keeps published facts documents bounded and verifiable cheaply.

Solutions

1. Measure canonicalize(payload).length and trim the payload below MAX_PAYLOAD_BYTES
2. Split the facts into multiple payloads and publish several envelopes
3. Remove bulky or redundant facts (large strings, duplicated entries)
4. If the limit is genuinely too small, raise MAX_PAYLOAD_BYTES deliberately in the script and republish with awareness that verifiers may enforce it too

Example fix

// before
await buildEnvelope({ privateKey, keyId, payload: { channel, facts_version, facts: allFacts } });
// after
const json = canonicalize(payload);
if (Buffer.byteLength(json) > MAX_PAYLOAD_BYTES) {
  payload.facts = payload.facts.slice(0, 100); // trim
}
await buildEnvelope({ privateKey, keyId, payload });

import { canonicalize, MAX_PAYLOAD_BYTES } from './facts-publish.mjs';
const bytes = Buffer.from(canonicalize(payload), 'utf8');
if (bytes.length > MAX_PAYLOAD_BYTES) throw new Error(`payload ${bytes.length}B > limit ${MAX_PAYLOAD_BYTES}B; trim facts`);

const fitsPayloadLimit = (payload) => Buffer.byteLength(canonicalize(payload), 'utf8') <= MAX_PAYLOAD_BYTES;

try { env = buildEnvelope({ privateKey, keyId, payload }); } catch (e) { if (e.message.includes('payload exceeds')) { console.error('Shrink the facts payload or split into batches'); process.exit(2); } throw e; }

When it happens

Trigger: buildEnvelope({ privateKey, keyId, payload }) where Buffer.from(canonicalize(payload)).length > MAX_PAYLOAD_BYTES — i.e. the canonical JSON of the facts payload exceeds the byte budget.

Common situations: Accumulating too many facts in one publish; embedding large blobs or verbose generated data in the payload; a change in canonicalization that inflates output (e.g. more escaped unicode); forgetting to prune stale facts.

Understand the failure class

Background: payload too large / request exceeds maximum size: why libraries cap bytes and how to fix oversize payloads — this error's family across 50 libraries.

Related errors

• download exceeds compressed size cap of bytes
• estimated_retained_payload_bytes is smaller than the frozen…
• Fleet artifact exceeds the 16 MiB limit
• Invalid local connection file.
• memory note exceeds bytes

AI-assisted analysis of Hmbown/CodeWhale@433685b202 (2026-09-15). Data as JSON: /api/errors/55b6775b5aba4957. Report an issue: GitHub.

Appendix: source

Thrown at web/scripts/facts-publish.mjs:298

    published_at: publishedAt,
    applies_to: typeof source.applies_to === "string" ? source.applies_to.trim() : "*",
    models: source.models ?? [],
    provider_defaults: source.provider_defaults ?? {},
    release: source.release ?? null,
    announcements: source.announcements ?? [],
  };
  if (source.not_after) payload.not_after = source.not_after;
  const payloadErrors = validateSource(payload);
  if (payloadErrors.length || utcTime(publishedAt) === null || !Number.isSafeInteger(factsVersion) || factsVersion <= 0 || !CHANNEL_RE.test(channel)) {
    throw new Error("invalid signed payload metadata");
  }
  return payload;
}

export function buildEnvelope({ privateKey, keyId, payload }) {
  if (!KEY_ID_RE.test(keyId)) throw new Error(`key_id must match ${KEY_ID_RE}`);
  const payloadBytes = Buffer.from(canonicalize(payload), "utf8");
  if (payloadBytes.length > MAX_PAYLOAD_BYTES) throw new Error(`payload exceeds ${MAX_PAYLOAD_BYTES} bytes`);
  const sig = signPayload(privateKey, keyId, payloadBytes);
  const sha256 = createHash("sha256").update(payloadBytes).digest("hex");
  const envelope = {
    envelope: ENVELOPE_VERSION,
    channel: payload.channel,
    facts_version: payload.facts_version,
    schema_version: payload.schema_version,
    key_id: keyId,
    alg: "ed25519",
    applies_to: payload.applies_to,
    published_at: payload.published_at,
    payload_b64: payloadBytes.toString("base64"),
    sig_b64: sig.toString("base64"),
    sigs: [],
    sha256,
  };
  if (payload.not_after != null) envelope.not_after = payload.not_after;
  const pub = rawPublicKeyFromKeyObject(createPublicKey(privateKey)).toString("base64");

View on GitHub (pinned to 433685b202)