coleam00/Archon · error

Malformed embedded checksum: "${checksum}"

Error message

Malformed embedded checksum: "${checksum}"

What it means

parseEmbeddedChecksum validates the checksum string embedded in the built CLI binary. It throws when the value is not exactly 64 lowercase hex characters (a SHA-256 hex digest) after trimming, guarding against corrupted or stale embedded build metadata before it is used to verify the downloaded web dist tarball.

Source

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

/**
 * Upper bound on the `tar` child. Extracting the ~2 MB release archive takes
 * tens of milliseconds, so this leaves three orders of magnitude of headroom for
 * a slow disk. Its only job is to stop a stalled child from turning
 * `archon serve` into a silent permanent hang: the parent-owned stdin channel
 * that caused the observed stall is gone (#2924), but filesystem-side stalls on
 * windows were never ruled out, and there is no budget in production to end one.
 */
const EXTRACTION_TIMEOUT_MS = 60_000;

function toError(err: unknown): Error {
  return err instanceof Error ? err : new Error(String(err));
}

export function parseEmbeddedChecksum(checksum: string): string {
  const normalized = checksum.trim();
  if (!/^[0-9a-f]{64}$/.test(normalized)) {
    throw new Error(`Malformed embedded checksum: "${checksum}"`);
  }
  return normalized;
}

export interface ServeOptions {
  /** TCP port to bind. Ignored when downloadOnly is true. Range: 1–65535. */
  port?: number;
  /** Download the web UI and exit without starting the server. */
  downloadOnly?: boolean;
}

export async function serveCommand(opts: ServeOptions): Promise<number> {
  if (
    opts.port !== undefined &&
    (!Number.isInteger(opts.port) || opts.port < 1 || opts.port > 65535)
  ) {
    console.error(`Error: --port must be an integer between 1 and 65535, got: ${opts.port}`);
    return 1;

View on GitHub (pinned to 0773b97458)

Solutions

1. Rebuild the CLI through the official build pipeline (scripts/build-binaries.sh / owning package scripts) so the real SHA-256 checksum is embedded.
2. Download the latest released binary instead of a locally modified or dev one.
3. Inspect the embedded constant to confirm what value is actually baked in, and compare against the generated checksums file.
4. As an operator workaround on dev builds, rely on the non-embedded path (remote checksums download) rather than the embedded one.

Example fix

// before: dev binary with placeholder
const embedded = 'PLACEHOLDER';
// after: rebuild so the build script injects the digest
const embedded = '9f2c...64-hex-sha256...';

function isValidSha256Hex(s: string): boolean {
  return /^[0-9a-f]{64}$/.test(s.trim());
}
if (!isValidSha256Hex(embeddedChecksum)) {
  throw new Error('Embedded checksum missing or malformed; rebuild via official pipeline');
}

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

try {
  await serveCommand({ downloadOnly: true });
} catch (err) {
  if (err instanceof Error && err.message.startsWith('Malformed embedded checksum')) {
    // fall back to remote-checksums mode or rebuild the binary
  }
}

When it happens

Trigger: Calling parseEmbeddedChecksum (via downloadWebDist during serve --download) with an embedded checksum that is empty, truncated, uppercase, or contains non-hex characters — typically a binary built without the web-dist checksum injection step.

Common situations: Building the CLI with a custom/modified build script that skips checksum embedding; stale binary from before the checksum feature; hand-edited binary constants; running a dev build where the placeholder was never replaced.

Understand the failure class

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

Related errors

• Malformed checksum entry for ${filename}: "${line.trim()}"
• Checksum not found for ${filename} in checksums.txt
• No chat in context
• Gitea API error: ${String(response.status)} ${response.statu
• Gitea API error: ${String(response.status)}

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