coleam00/Archon · error · Error

Invalid container.pidsLimit '${String(pidsLimit)}' — must be

Error message

Invalid container.pidsLimit '${String(pidsLimit)}' — must be a positive integer.

What it means

resolveContainerBackendConfig() requires container.pidsLimit to be a positive integer when present. `docker run --pids-limit` rejects fractional and non-positive values, so the CLI enforces Number.isInteger and > 0 and throws this error before any docker call is made.

Source

Thrown at packages/cli/src/commands/workflow.ts:405

): ContainerBackendConfig {
  const network = cfg?.network;
  if (network !== undefined && network !== 'bridge' && network !== 'none') {
    throw new Error(
      `Invalid container.network '${network}' in .archon/config.yaml — must be ` +
        "'bridge' or 'none'. Host networking is not allowed for container isolation."
    );
  }
  // Positive INTEGERS — `docker run --memory`/`--pids-limit` reject fractions,
  // and Number.isFinite alone would let `512.5` through to a runtime docker error.
  const memoryMb = cfg?.memoryMb;
  if (memoryMb !== undefined && (!Number.isInteger(memoryMb) || memoryMb <= 0)) {
    throw new Error(
      `Invalid container.memoryMb '${String(memoryMb)}' — must be a positive integer (MiB).`
    );
  }
  const pidsLimit = cfg?.pidsLimit;
  if (pidsLimit !== undefined && (!Number.isInteger(pidsLimit) || pidsLimit <= 0)) {
    throw new Error(
      `Invalid container.pidsLimit '${String(pidsLimit)}' — must be a positive integer.`
    );
  }
  return {
    image: cfg?.image?.trim() || DEFAULT_RUNNER_IMAGE,
    network: network ?? 'bridge',
    memoryMb: memoryMb ?? 4096,
    pidsLimit: pidsLimit ?? 512,
  };
}

/**
 * H2 — a container run has an UNRESOLVED write-back when its overlay diff was raised
 * for review (`pending_writeback` set) but never applied or discarded
 * (`writeback_resolved !== true`). This happens on a failed/partial apply. The CLI
 * teardown must PRESERVE the container+volume in this state (the overlay is the only
 * copy of the changes) rather than destroy it. Pure so the decision is unit-testable.
 */

View on GitHub (pinned to 0773b97458)

Solutions

  1. Set `container.pidsLimit` to a positive integer, e.g. `pidsLimit: 256`.
  2. Remove the `pidsLimit` key entirely if you do not want a limit.
  3. Validate your YAML types — unquoted values must parse as numbers, not strings.

Example fix

// .archon/config.yaml (before)
container:
  pidsLimit: 0
// after
container:
  pidsLimit: 256
Defensive patterns

Strategy: validation

Validate before calling

const p = cfg?.container?.pidsLimit;
if (p !== undefined && (!Number.isInteger(p) || p <= 0)) {
  throw new Error(`container.pidsLimit must be a positive integer, got: ${String(p)}`);
}

Type guard

function isPositiveInteger(v: unknown): v is number {
  return typeof v === 'number' && Number.isInteger(v) && v > 0;
}

Try / catch

try {
  await runWorkflow(name, opts);
} catch (e) {
  if (String((e as Error).message).includes('Invalid container.pidsLimit')) {
    console.error('Set container.pidsLimit to a positive integer or remove the key.');
  }
}

Prevention

When it happens

Trigger: container.pidsLimit in .archon/config.yaml is a float (e.g. 100.5), zero, negative, or a non-numeric value (string 'auto', null, YAML boolean) when resolveContainerBackendConfig runs during workflow start.

Common situations: Setting pidsLimit: 0 believing it means 'unlimited' (it must be positive; remove the key instead); copying a float; leaving a placeholder string from a template.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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