OpenCode evals require exact version 1.18.29; received

Error message

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

What it means

OpenCode eval sessions pin the provider binary to exactly version 1.18.29 so eval results are reproducible; evalSessionProviderVersion throws for any other requested version and defaults to the pinned one when none is supplied.

Solutions

Set request.opencodeVersion to '1.18.29' (or omit it to use the default)
Install/pin the OpenCode binary at exactly 1.18.29 in the environment
Update the pinned version constant in eval-session.ts if the eval matrix legitimately moves

Example fix

// before
runEval({ provider: 'opencode', opencodeVersion: '1.19.0' });
// after
runEval({ provider: 'opencode', opencodeVersion: '1.18.29' });

Defensive patterns

Strategy: validation

Validate before calling

if ((request.provider === 'opencode') && request.opencodeVersion !== undefined && request.opencodeVersion !== '1.18.29') throw new Error('opencode evals pinned to 1.18.29');

Type guard

function isPinnedOpenCodeVersion(v: string | undefined): boolean { return (v ?? '1.18.29') === '1.18.29'; }

Try / catch

try { runEvalSession(request); }
catch (e) { if (String(e.message).startsWith('OpenCode evals require exact version')) { console.error('Pin opencodeVersion to 1.18.29'); process.exitCode = 2; } else throw e; }

Prevention

Pin the OpenCode binary version in CI and dev setup to 1.18.29
Omit opencodeVersion to inherit the pinned default instead of passing a dynamic version
Centralize the pin constant rather than repeating versions in configs

When it happens

Trigger: Requesting an eval session with provider 'opencode' and opencodeVersion set to anything other than '1.18.29' (e.g. '1.18.30', 'latest', '1.19.0').

Common situations: CI installing the newest OpenCode release; a developer bumping the local CLI and re-running evals; a config template interpolating a version variable.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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

Appendix: source

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

  });
}

export function evalRuntimeSystemInstructions(
  runtimeContext: NativeRuntimeContextSnapshot,
): string {
  return composeNativeSystemInstructions(
    runtimeContext,
    EVAL_RUNTIME_INSTRUCTIONS,
  );
}

export function evalSessionProviderVersion(
  request: EvalSessionRequest,
): string | null {
  if (request.provider === "opencode") {
    const version = request.opencodeVersion ?? "1.18.29";
    if (version !== "1.18.29") {
      throw new Error(`OpenCode evals require exact version 1.18.29; 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!.qualificationRevision;
  }
  return null;
}

View on GitHub (pinned to 01ad858492)