What causes "Malformed checksum entry for ${filename}: "${line.trim()}"" in coleam00/Archon?

Inspect the quoted line in the message and correct the checksums.txt so the entry is ` archon-web.tar.gz` (lowercase sha256).

coleam00/Archon · error

Malformed checksum entry for ${filename}: "${line.trim()}"

Error message

Malformed checksum entry for ${filename}: "${line.trim()}"

What it means

parseChecksum scans a checksums.txt body for a line whose second whitespace-separated field equals the requested filename, then validates the first field is a 64-char lowercase hex sha256. If a matching line exists but its hash field is malformed, it throws this error naming the offending line. This guards against a tampered or corrupted checksums file producing a bogus expected hash.

Source

Thrown at packages/cli/src/commands/serve.ts:301

  console.log(`Extracted to ${targetDir}`);
}

function cleanupAndThrow(tmpDir: string, message: string): never {
  rmSync(tmpDir, { recursive: true, force: true });
  throw new Error(message);
}

/**
 * Parse a SHA-256 checksum from a checksums.txt file (sha256sum format).
 * Format: `<hash>  <filename>` or `<hash> <filename>`
 */
export function parseChecksum(checksums: string, filename: string): string {
  for (const line of checksums.split('\n')) {
    const parts = line.trim().split(/\s+/);
    if (parts.length >= 2 && parts[1] === filename) {
      const hash = parts[0];
      if (!/^[0-9a-f]{64}$/.test(hash)) {
        throw new Error(`Malformed checksum entry for ${filename}: "${line.trim()}"`);
      }
      return hash;
    }
  }
  throw new Error(`Checksum not found for ${filename} in checksums.txt`);
}

View on GitHub (pinned to 0773b97458)

Solutions

Inspect the quoted line in the message and correct the checksums.txt so the entry is `<64-hex> archon-web.tar.gz` (lowercase sha256).
Re-download checksums.txt from the official release to replace a corrupted/mangled local copy.
Regenerate with `sha256sum archon-web.tar.gz > checksums.txt` if you built the artifact locally.
Confirm no proxy/AV is rewriting the downloaded text file before parsing.

Example fix

// before (checksums.txt)
ABC123  archon-web.tar.gz   // uppercase short hash -> Malformed checksum entry
// after
9f2c...64-hex-lowercase...  archon-web.tar.gz

Defensive patterns

Strategy: validation

Validate before calling

// Validate the manifest before passing it to parseChecksum
const line = checksumsText
  .split('\n')
  .find((l) => l.trim().split(/\s+/)[1] === 'archon-web.tar.gz');
if (line && !/^[0-9a-f]{64}(\s|$)/.test(line.trim())) {
  throw new Error(`checksums.txt has a malformed sha256 for archon-web.tar.gz: "${line.trim()}" — refetch the official manifest`);
}

Type guard

function isSha256Hex(value: string): value is `${string}` {
  return /^[0-9a-f]{64}$/.test(value);
}

Try / catch

try {
  await serveCommand();
} catch (err) {
  if (err instanceof Error && err.message.startsWith('Malformed checksum entry')) {
    // the offending line is quoted in the message; replace the local
    // checksums.txt with the official release copy and retry.
  } else throw err;
}

Prevention

Never hand-edit checksums.txt; regenerate with sha256sum when building locally.
Fetch the manifest fresh from the release instead of caching copies.
Use lowercase hex sha256 digests; other tools may emit uppercase or non-sha256 hashes.
Keep one generator for the manifest so hash algorithm and format can't drift.

When it happens

Trigger: downloadWebDist -> parseChecksum(checksumsText, 'archon-web.tar.gz') finds a line whose second column matches the filename but whose first column fails /^[0-9a-f]{64}$/: checksums.txt fetched from the wrong URL (HTML error page with a coincidental match is unlikely; more likely a truncated or hand-edited file), an uppercase hash, a short/abbreviated hash, or a wrapped line.

Common situations: Manually edited checksums.txt; a proxy or script that mangled the file; a release tool emitting a different hash algorithm (e.g. md5) in the same file; copying an uppercase digest from a different generator.

Understand the failure class

Background: Checksum mismatch errors: "checksum verification failed", "digest mismatch", "expected vs actual checksum" — what they mean and how to fix them — this error's family across 41 libraries.

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

AI-assisted analysis of coleam00/Archon@0773b97458 (2026-09-01). Data as JSON: /api/errors/67a03158c1bb9d7a. Report an issue: GitHub.