paperclipai/paperclip · error · Error

Pinned OpenCode materialization requires linux/x64, received

Error message

Pinned OpenCode materialization requires linux/x64, received ${platform}/${architecture}

What it means

materializePinnedOpenCodeBinary only supports hard-linking the pinned OpenCode binary on linux/x64. On any other platform or architecture it throws immediately because the materialization path is only validated there.

Source

Thrown at packages/paperclip-runner/scripts/materialize-opencode-binary.mjs:43

}

function assertPackage(packageRoot, expectedName) {
  const packageJson = readPackage(join(packageRoot, "package.json"));
  if (
    packageJson.name !== expectedName ||
    packageJson.version !== OPENCODE_VERSION
  ) {
    throw new Error(
      `Expected ${expectedName}@${OPENCODE_VERSION}, received ${String(packageJson.name)}@${String(packageJson.version)}`,
    );
  }
}

export function materializePinnedOpenCodeBinary(options = {}) {
  const platform = options.platform ?? process.platform;
  const architecture = options.architecture ?? process.arch;
  if (platform !== "linux" || architecture !== "x64") {
    throw new Error(
      `Pinned OpenCode materialization requires linux/x64, received ${platform}/${architecture}`,
    );
  }

  const packageRoot = realpathSync(
    options.packageRoot ??
      resolve(import.meta.dirname, "../node_modules/opencode-ai"),
  );
  const dependencyRoot = dirname(packageRoot);
  const baselineRoot = realpathSync(join(dependencyRoot, BASELINE_PACKAGE));
  assertPackage(packageRoot, "opencode-ai");
  assertPackage(baselineRoot, BASELINE_PACKAGE);

  const source = join(baselineRoot, "bin", "opencode");
  const target = join(packageRoot, "bin", "opencode.exe");
  if (!lstatSync(source).isFile()) {
    throw new Error("Pinned OpenCode source executable is not a regular file");
  }

View on GitHub (pinned to 01ad858492)

Solutions

Run the materialization on a linux/x64 machine (native host, x86_64 container, or linux/x64 CI runner).
If passing options.platform/options.architecture for testing, only use { platform: 'linux', architecture: 'x64' } with mocked fs, not in real materialization.
For arm64 support, extend the script with a validated baseline for that platform rather than removing the guard.
Condition the call in setup scripts when platform is not linux/x64.

Example fix

// before
await materializePinnedOpenCodeBinary(); // run anywhere
// after
if (process.platform === 'linux' && process.arch === 'x64') {
  await materializePinnedOpenCodeBinary();
}

Defensive patterns

Strategy: fallback

Validate before calling

if (process.platform !== 'linux' || process.arch !== 'x64') {
  console.warn('Skipping pinned OpenCode materialization: requires linux/x64');
}

Type guard

function supportsPinnedOpenCode(platform = process.platform, arch = process.arch) {
  return platform === 'linux' && arch === 'x64';
}

Try / catch

try {
  materializePinnedOpenCodeBinary();
} catch (err) {
  if (/requires linux\/x64/.test(err.message)) {
    console.warn('Materialization skipped on this platform');
  } else throw err;
}

Prevention

Gate the call behind a platform/arch check in setup scripts.
Run cross-platform builds inside an x86_64 Linux container.
Document the linux/x64 requirement in the script's help text.
Only pass fake platform/arch options in unit tests with mocked fs.

When it happens

Trigger: Calling materializePinnedOpenCodeBinary on macOS, Windows, arm64 Linux, or passing explicit options.platform/options.architecture values other than linux/x64.

Common situations: A developer runs the script on a MacBook; CI runs on an arm64 runner; a test passes fake platform/architecture options.

Understand the failure class

Background: "unsupported platform" / "not supported on this platform" errors: what they mean and how to fix them — this error's family across 47 libraries.

Related errors

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-09-10). Data as JSON: /api/errors/256f1a7a5efd6f90. Report an issue: GitHub.