paperclipai/paperclip · error

OpenCode ${version} is not the question-conformance-qualifie

Error message

OpenCode ${version} is not the question-conformance-qualified ${QUALIFIED_OPENCODE_VERSION}

What it means

Thrown when the OpenCode server's reported version is valid semver but does not exactly equal QUALIFIED_OPENCODE_VERSION. The driver is qualified (question-conformance tested) against one specific version and refuses any other, whether newer or older.

Source

Thrown at packages/paperclip-runner/src/drivers/opencode/opencode-server-driver.ts:2024

      });
    const baseUrl = `http://127.0.0.1:${port}`;
    const health = await waitForHealth(
      baseUrl,
      authHeader,
      input.options.fetch ?? globalThis.fetch,
      child,
      () => diagnostics,
      input.trace,
    );
    const version = text(record(health).version);
    if (!/^\d+\.\d+\.\d+$/.test(version))
      throw new Error("OpenCode health response omitted a semantic version");
    const qualifiedComparison = compareVersion(
      version,
      QUALIFIED_OPENCODE_VERSION,
    );
    if (qualifiedComparison !== 0) {
      throw new Error(
        `OpenCode ${version} is not the question-conformance-qualified ${QUALIFIED_OPENCODE_VERSION}`,
      );
    }
    return {
      baseUrl,
      authHeader,
      version,
      permissionMode: input.options.permissionMode ?? "allow",
      process: child,
      bridge,
      trace: input.trace,
      sensitiveValues: [
        password,
        input.options.environment?.OPENROUTER_API_KEY,
      ].filter((value): value is string => Boolean(value)),
      close: async (closeInput = {}) => {
        await bridge.close().catch(() => {});
        if (child.exitCode === null && child.signalCode === null && child.pid) {

View on GitHub (pinned to 01ad858492)

Solutions

1. Install exactly the qualified OpenCode version the driver expects (read QUALIFIED_OPENCODE_VERSION in opencode-server-driver.ts) — e.g. pin it in package.json or the install script.
2. Check that PATH resolves the intended opencode binary (which opencode) rather than a globally installed different version.
3. If you intentionally upgraded, bump QUALIFIED_OPENCODE_VERSION only after re-running the question-conformance qualification.
4. In CI, pin the OpenCode version in the Docker image / setup step to match the driver constant.

Example fix

// before
npm install -g opencode-ai@latest

// after
npm install -g opencode-ai@1.2.3 // exact QUALIFIED_OPENCODE_VERSION

const { version } = await (await fetch(`${baseUrl}/health`)).json();
if (version !== QUALIFIED_OPENCODE_VERSION) throw new Error(`Pin opencode to ${QUALIFIED_OPENCODE_VERSION}, found ${version}`);

try {
  await startDriver();
} catch (e) {
  if (e instanceof Error && /is not the question-conformance-qualified/.test(e.message)) {
    // message contains both versions — install the qualified one and retry
  }
}

When it happens

Trigger: compareVersion(version, QUALIFIED_OPENCODE_VERSION) returns non-zero — any install of OpenCode other than the pinned qualified version, including patch-level differences.

Common situations: npm/pnpm auto-upgraded OpenCode; CI image pinned a different version than the driver expects; developer locally runs a newer OpenCode than the qualified constant; the qualified constant was bumped without updating the installed binary.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

• OpenCode health response omitted a semantic version
• Request failed with status ${response.status}
• Adapter declares unsupported UI parser contract version — sk
• Managed restart did not produce healthy runtime services.
• Anthropic did not return a usable pinned Agent version

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