archive is too large

Error message

archive is too large (${size} bytes; the maximum is ${MAX_ARCHIVE_BYTES})

What it means

readArchiveFile stats the file before reading it, because readFileSync pulls the whole document into memory, and rejects any file larger than MAX_ARCHIVE_BYTES before that read happens. The message mirrors the Windhawk core's own oversized-archive rejection so the caller's catch surfaces a familiar error.

Solutions

Shrink the archive: remove bundled binaries, compress assets, or exclude build artifacts and repack the mod.
Verify you selected the intended .whl file and not a build output or backup.
Check the reported byte count against MAX_ARCHIVE_BYTES in extension.ts to see how far over the limit the file is.
If the mod legitimately needs the payload, split it or host the large assets separately rather than inside the archive.

Example fix

// before
const src = readArchiveFile(selectedFile); // throws at 60 MB archive
// after
const { size } = fs.statSync(selectedFile);
if (size > MAX_ARCHIVE_BYTES) size = await shrinkArchive(selectedFile);
const src = readArchiveFile(selectedFile);

Defensive patterns

Strategy: validation

Validate before calling

import fs from 'fs';
const MAX = 50 * 1024 * 1024; // keep in sync with MAX_ARCHIVE_BYTES in extension.ts
const { size } = fs.statSync(archivePath);
if (size > MAX) {
  throw new Error(`archive too large: ${size} > ${MAX}`);
}

Try / catch

try {
  await importMod(archivePath);
} catch (e) {
  if (/archive is too large/.test(e.message)) {
    promptUserToShrinkArchive(archivePath);
  } else { throw e; }
}

Prevention

Exclude build artifacts, binaries and dependency folders from mod archives.
Check archive size with stat before submitting whenever the archive is assembled programmatically.
Re-pack compressed assets if the archive drifts close to the limit.
Keep MAX_ARCHIVE_BYTES in sync between packaging scripts and the extension.

When it happens

Trigger: Selecting/submitting a mod archive (.whl) whose byte size exceeds MAX_ARCHIVE_BYTES — importing a mod from disk, or packing a mod whose embedded binaries/bundles grew past the limit.

Common situations: A mod archive accidentally contains large binaries (compiled DLLs, resources, node_modules) ballooning its size; picking the wrong file (a build artifact or backup) in the import dialog; older mods became invalid after the limit was tightened.

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 ramensoftware/windhawk@61d99ed8e1 (2026-09-12). Data as JSON: /api/errors/e5a61ee2f72f53fc. Report an issue: GitHub.

Appendix: source

Thrown at src/windhawk-vscode/src/extension.ts:1965

// are self-describing and sort chronologically. The archive's own exportedAt is
// core-stamped in UTC and independent of this name.
function defaultBackupFileName(): string {
	const now = new Date();
	const p = (n: number) => String(n).padStart(2, '0');
	return (
		`${now.getFullYear()}-${p(now.getMonth() + 1)}-${p(now.getDate())}-` +
		`${p(now.getHours())}h${p(now.getMinutes())}m${p(now.getSeconds())}-windhawk-backup.json`
	);
}

// Read a picked archive file, refusing one past the core's cap by its SIZE first:
// the read pulls the whole document into memory, so a file that cannot be a valid
// archive must be rejected before it is read rather than after. The message is
// worded like the core's own rejection, and the caller's catch surfaces it.
function readArchiveFile(filePath: string): string {
	const { size } = fs.statSync(filePath);
	if (size > MAX_ARCHIVE_BYTES) {
		throw new Error(
			`archive is too large (${size} bytes; the maximum is ${MAX_ARCHIVE_BYTES})`
		);
	}
	return fs.readFileSync(filePath, 'utf8');
}

// The short architecture label Windows users recognize - the vocabulary of the
// Settings "System type" and Task Manager - for each clang target triple.
// Mirrors the core hosts' table (windhawk-core core-host/src/arch.rs). An
// unrecognized triple is surfaced verbatim rather than hidden.
const archLabels: Record<string, string> = {
	'i686-w64-mingw32': 'x86',
	'x86_64-w64-mingw32': 'x64',
	'aarch64-w64-mingw32': 'ARM64',
};

// Rewrite a forwarded compile sub-event's compileTarget from the raw clang triple
// the core emits to the arch label, so the webview's "Compiling <mod> for

View on GitHub (pinned to 61d99ed8e1)