OpenCode evals require exact version 1.18.17; received ${ver

Error message

OpenCode evals require exact version 1.18.17; received ${version}

What it means

providerVersion pins OpenCode eval sessions to exactly version 1.18.17. If request.opencodeVersion is set to anything else (or, conceptually, if the default pin ever changes upstream), the eval session refuses to start. This keeps eval artifacts reproducible against a single qualified harness version.

Source

Thrown at packages/paperclip-runner/src/cli/eval-session.ts:60

      throw new Error(`unknown argument: ${args[index] ?? ""}`);
    }
    if (args[index + 1] === undefined) throw new Error(`missing ${args[index]}`);
  }
  return {
    requestPath: argument(args, "--request"),
    outputPath: argument(args, "--output"),
  };
}

async function sha256(path: string): Promise<string> {
  return createHash("sha256").update(await readFile(path)).digest("hex");
}

function providerVersion(request: EvalSessionRequest): string | null {
  if (request.provider === "opencode") {
    const version = request.opencodeVersion ?? "1.18.17";
    if (version !== "1.18.17") {
      throw new Error(`OpenCode evals require exact version 1.18.17; received ${version}`);
    }
    return version;
  }
  if (request.provider === "acpx") {
    return resolveQualifiedAcpxProfile(
      request.acpxAgent ?? "codex",
      request.model,
    ).acpxVersion;
  }
  if (request.provider === "claude_managed") {
    return request.managedProfile!.agentVersion;
  }
  if (request.provider === "aws_agentcore") {
    return request.agentCoreProfile!.harnessVersion;
  }
  return null;
}

View on GitHub (pinned to 5716fe907e)

Solutions

Remove opencodeVersion from the request JSON so the built-in pin "1.18.17" applies
Set opencodeVersion explicitly to "1.18.17" in the request file
If a newer opencode is genuinely required, this is an intentional pin: update the qualified version in packages/paperclip-runner (and its tests) deliberately, not per-request

Example fix

// before (request JSON)
{ "provider": "opencode", "opencodeVersion": "1.19.0", ... }
// after
{ "provider": "opencode", "opencodeVersion": "1.18.17", ... }

Defensive patterns

Strategy: validation

Validate before calling

const REQUIRED_OPENCODE_VERSION = "1.18.17";
function assertValidOpencodeRequest(request: { provider?: string; opencodeVersion?: string }): void {
  if (request.provider === "opencode" &&
      request.opencodeVersion !== undefined &&
      request.opencodeVersion !== REQUIRED_OPENCODE_VERSION) {
    throw new Error(
      `opencodeVersion must be "${REQUIRED_OPENCODE_VERSION}" or omitted (got ${request.opencodeVersion})`,
    );
  }
}

Type guard

function hasPinnedOpencodeVersion(request: { opencodeVersion?: string }): boolean {
  return request.opencodeVersion === undefined || request.opencodeVersion === "1.18.17";
}

Try / catch

try {
  await runEvalSessionCli(args);
} catch (error) {
  if (error instanceof Error && error.message.includes("require exact version 1.18.17")) {
    console.error(`Unsupported opencode version: ${error.message}. Pin opencodeVersion to "1.18.17" or omit it.`);
    process.exitCode = 1;
    return;
  }
  throw error;
}

Prevention

Omit opencodeVersion from request JSON and let the built-in pin apply
Do not template opencodeVersion from environment variables or lockfiles in eval request generators
When intentionally upgrading the qualified opencode, update the pin in packages/paperclip-runner and regenerate all request fixtures in the same change
Add a schema/Zod validator on the request JSON that rejects non-pinned opencodeVersion values before invoking the CLI

When it happens

Trigger: Building an EvalSessionRequest JSON with provider "opencode" and opencodeVersion set to any value other than "1.18.17" (e.g. "1.19.0", "latest", "1.18"). Omitting the field is fine — it defaults to "1.18.17".

Common situations: Upgrading opencode locally and updating the request file to match; templating the version from an environment variable or package manager output; hand-editing a request JSON copied from an older/newer eval.

Related errors

AI-assisted analysis of paperclipai/paperclip@5716fe907e (2026-09-02). Data as JSON: /api/errors/be02216be328243a. Report an issue: GitHub.