paperclipai/paperclip · error · Error

ACPX runtime does not expose session config controls; upgrad

Error message

ACPX runtime does not expose session config controls; upgrade ACPX or remove configured model, effort, and fast mode overrides.

What it means

Thrown by applySessionConfigOptions when the user has configured model, thinking-effort, or fast-mode overrides for an ACPX agent (other than claude/codex, which are handled via env vars) and the runtime object does not implement the setConfigOption method. The function first builds a list of config options from the prepared runtime; if any exist and the runtime lacks the setConfigOption capability, it logs to stderr and throws.

Source

Thrown at packages/adapter-utils/src/acpx-engine/execute.ts:2164

      { key: "features.fast_mode", value: "true" },
    );
  }
  return options;
}

async function applySessionConfigOptions(input: {
  runtime: AcpRuntime;
  handle: AcpRuntimeHandle;
  prepared: AcpxPreparedRuntime;
  onLog: AdapterExecutionContext["onLog"];
}) {
  const options = sessionConfigOptions(input.prepared);
  if (options.length === 0) return;
  if (!input.runtime.setConfigOption) {
    const message =
      "ACPX runtime does not expose session config controls; upgrade ACPX or remove configured model, effort, and fast mode overrides.";
    await input.onLog("stderr", `[paperclip] ${message}\n`);
    throw new Error(message);
  }
  for (const option of options) {
    await input.runtime.setConfigOption({
      handle: input.handle,
      key: option.key,
      value: option.value,
    });
    await input.onLog(
      "stdout",
      `[paperclip] Applied ACPX ${input.prepared.acpxAgent} config ${option.key}=${option.value}\n`,
    );
  }
}

/**
 * Build the process-session launch env: the host env overlaid with the run's
 * `env` (so the merged paperclip bridge vars win) and a guaranteed `PATH`,
 * narrowed to string values. Shared by the remote concurrent bring-up and the

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Upgrade the ACPX runtime to a version that implements setConfigOption.
2. Remove the model, effort, and fast-mode overrides from the agent configuration so sessionConfigOptions returns an empty array.
3. If using claude or codex agents, model/effort config is handled via startup env vars—switch to one of those agents if the overrides are essential.
4. Check the AcpRuntime type definition to confirm whether your runtime version exposes setConfigOption.

Example fix

// before: agent config with model override on unsupported runtime
const agentConfig = {
  acpxAgent: "gemini-cli",
  requestedModel: "gemini-2.0-flash",
};

// after: remove the override (let the runtime use its default)
const agentConfig = {
  acpxAgent: "gemini-cli",
  // requestedModel removed
};

// or upgrade ACPX so runtime.setConfigOption is defined

function hasSessionConfigOverrides(prepared: { requestedModel?: string; requestedThinkingEffort?: string; fastMode?: boolean; acpxAgent: string }): boolean {
  const needsConfigOption = prepared.acpxAgent !== 'claude' && prepared.acpxAgent !== 'codex';
  if (!needsConfigOption) return false;
  return Boolean(prepared.requestedModel || prepared.requestedThinkingEffort || prepared.fastMode);
}

// Call before applySessionConfigOptions:
if (hasSessionConfigOverrides(prepared) && !runtime.setConfigOption) {
  throw new Error('Runtime lacks setConfigOption; remove model/effort/fastMode overrides or upgrade ACPX.');
}

function runtimeSupportsConfigOption(runtime: unknown): runtime is { setConfigOption: (input: { handle: unknown; key: string; value: string }) => Promise<void> } {
  return typeof runtime === 'object' && runtime !== null && typeof (runtime as any).setConfigOption === 'function';
}

try {
  await applySessionConfigOptions({ runtime, handle, prepared, onLog });
} catch (error) {
  if (error instanceof Error && error.message.includes('does not expose session config controls')) {
    // Remove overrides and retry, or upgrade the ACPX runtime
    console.error('Either upgrade ACPX or remove model/effort/fastMode config for this agent.');
  }
  throw error;
}

When it happens

Trigger: Running an ACPX-backed agent (not claude or codex) with a configured model override (requestedModel), thinking-effort override (requestedThinkingEffort), or fast mode (fastMode) when the ACP runtime version does not implement setConfigOption. This occurs during adapter execution in the ACPX engine when session config options are being applied.

Common situations: Using an older version of the ACP/ACPX runtime that predates the setConfigOption API. A version mismatch between the adapter-utils package and the installed ACPX runtime. Configuring model/effort/fast-mode in the agent config for a runtime that does not support runtime config overrides.

Related errors

• Failed to parse JSON at ${filePath}: ${err instanceof Error
• Company ID is required. Pass --company-id, set PAPERCLIP_COM
• Import transfer declaration returned no data.
• Company ID is required. Pass --company-id, set PAPERCLIP_COM
• Company ID is required. Pass --company-id, set PAPERCLIP_COM

AI-assisted analysis of paperclipai/paperclip@67001ec6eb (2026-08-12). Data as JSON: /api/errors/0a3b0c20250b2c6e. Report an issue: GitHub.