Hmbown/CodeWhale · error · Error

file exceeds size limit

Error message

file exceeds size limit

What it means

readBoundedFile reads at most maxBytes+1 bytes and throws this error if it actually accumulated more than maxBytes, meaning the file grew past the bound during the read even though the pre-read stat looked acceptable. It is the final size gate for bounded reads.

Solutions

  1. Check the file size (`wc -c`) and confirm it fits the limit
  2. Pass exactly one PEM key in the file, not a bundle
  3. Use the CODEWHALE_FACTS_SIGNING_KEY env var with the PEM contents instead of a file
  4. Extract the single key you need into a fresh small file

Example fix

// before
CODEWHALE_FACTS_SIGNING_KEY_FILE=./all-keys.pem  # 40 KiB bundle
// after
grep -B1 -A4 'BEGIN PRIVATE KEY' all-keys.pem | head -6 > key.pem
CODEWHALE_FACTS_SIGNING_KEY_FILE=./key.pem
Defensive patterns

Strategy: validation

Validate before calling

const st = statSync(path);
if (st.size > MAX_ENVELOPE_BYTES) throw new Error(`${path} is ${st.size}B, limit is ${MAX_ENVELOPE_BYTES}B`);

Type guard

const fitsSizeLimit = (path, max = MAX_ENVELOPE_BYTES) => { try { return statSync(path).size <= max; } catch { return false; } };

Try / catch

try { bytes = readBoundedFile(file, 16 * 1024); } catch (e) { if (e.message === 'file exceeds size limit') { console.error(`${file} too large — provide a single PEM key under the limit`); process.exit(2); } throw e; }

Prevention

When it happens

Trigger: readBoundedFile(path, maxBytes) where the read loop collected size > maxBytes — the file exceeded the size cap (default MAX_ENVELOPE_BYTES, or 16 KiB when reading the signing key file).

Common situations: Pointing CODEWHALE_FACTS_SIGNING_KEY_FILE at a full keychain or concatenated PEM bundle larger than 16 KiB; the file being appended to between stat and read; wrong file passed (e.g. a bundle instead of a single key).

Understand the failure class

Background: "File too large" / "file size exceeds limit" errors: why libraries cap file sizes and how to fix them — this error's family across 46 libraries.

Related errors

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

Appendix: source

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

  return { positional, flags };
}

/** Bounded, regular, single-link file reads; no symlink or FIFO following. */
export function readBoundedFile(path, maxBytes = MAX_ENVELOPE_BYTES) {
  const before = lstatSync(path);
  if (!before.isFile() || before.nlink !== 1) throw new Error("file is not a regular single-link file");
  const fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
  try {
    const stat = fstatSync(fd);
    if (!stat.isFile() || stat.nlink !== 1 || stat.size > maxBytes || stat.ino !== before.ino || stat.dev !== before.dev) throw new Error("file is not a bounded regular single-link file");
    const bytes = Buffer.alloc(maxBytes + 1);
    let size = 0;
    while (size <= maxBytes) {
      const count = readSync(fd, bytes, size, maxBytes + 1 - size, null);
      if (!count) break;
      size += count;
    }
    if (size > maxBytes) throw new Error("file exceeds size limit");
    return bytes.subarray(0, size);
  } finally { closeSync(fd); }
}

function loadPrivateKeyFromEnv() {
  refuseUnderCi();
  let pem = process.env.CODEWHALE_FACTS_SIGNING_KEY;
  const file = process.env.CODEWHALE_FACTS_SIGNING_KEY_FILE;
  if (!pem && file) pem = readBoundedFile(file, 16 * 1024).toString("utf8");
  if (!pem) throw new Error("set CODEWHALE_FACTS_SIGNING_KEY (PEM) or CODEWHALE_FACTS_SIGNING_KEY_FILE");
  if (Buffer.byteLength(pem) > 16 * 1024) throw new Error("signing key exceeds size limit");
  const key = createPrivateKey({ key: pem, format: "pem" });
  if (key.asymmetricKeyType !== "ed25519") throw new Error("signing key must be Ed25519");
  return key;
}

export function validateTrustedKeys(keys) {
  const seen = new Set();

View on GitHub (pinned to 433685b202)