paperclipai/paperclip · error

ACPX session profile differs from its initialization

Error message

ACPX session profile differs from its initialization

What it means

After initialization, the ACPX sidecar validates that each session/open request's agent and model match the agent/model it was initialized with. If parsed params differ from initializedAgent or initializedModel, dispatch throws this error because one sidecar process is bound to exactly one session profile.

Source

Thrown at packages/paperclip-runner/src/cli/acpx-runtime-sidecar.ts:253

    };
  }
  if (request.command === "session.open") {
    if (
      hasSidecarSessionOwnership(
        host,
        activeHostCleanup,
        failedAdmissionCleanup,
      )
    ) {
      throw new Error("ACPX sidecar already owns a session or its cleanup");
    }
    if (!initializedModel) throw new Error("initialize the ACPX sidecar first");
    const params = parseOpenParams(request.params);
    if (
      params.agent !== initializedAgent ||
      params.model !== initializedModel
    ) {
      throw new Error("ACPX session profile differs from its initialization");
    }
    const openedHost = await AcpxRuntimeHost.open(
      {
        runtimeDirectory: params.runtimeDirectory,
        normalizedSessionId: params.normalizedSessionId,
        workingDirectory: params.workingDirectory,
        agent: params.agent,
        model: params.model,
        permissionMode: params.permissionMode,
        systemInstructions: params.systemInstructions,
        environment: process.env,
        expectedIdentity: params.expectedIdentity,
        semanticTools: {
          tools: params.tools,
          handler: waitForTool,
        },
        onGoalUpdate: (goal) => {
          // Admission can emit a snapshot before the verified host is assigned.

View on GitHub (pinned to 01ad858492)

Solutions

1. Restart/re-initialize the sidecar with the desired agent+model before opening sessions with that profile
2. Send open params that exactly match the initialized agent and model (log both sides to compare)
3. If the profile must change, tear down the current sidecar and spawn a new one bound to the new profile
4. Cache the initialized profile client-side and validate before dispatch

Example fix

// before
sidecar.dispatch({ method: 'session/open', params: { agent, model: 'other-model' } });
// after
if (model !== sidecar.initializedProfile.model) {
  await sidecar.restart({ agent, model }); // re-init with new profile
}
sidecar.dispatch({ method: 'session/open', params: { agent, model } });

if (params.agent !== initializedProfile.agent || params.model !== initializedProfile.model) await respawnSidecar({ agent: params.agent, model: params.model });

const matchesProfile = (p: { agent: string; model: string }, init: { agent: string; model: string }) => p.agent === init.agent && p.model === init.model;

try { sidecar.dispatch(openRequest); } catch (e) { if (e.message === 'ACPX session profile differs from its initialization') { await respawnSidecar(openRequest.params); return sidecar.dispatch(openRequest); } throw e; }

When it happens

Trigger: Calling session/open with params.agent or params.model different from the values passed at initialize; a client reconnecting with changed defaults; passing stale cached params after the client's model selection changed.

Common situations: Switching models in the UI while reusing a long-lived sidecar; config reload changing the default model after sidecar startup; multiple agents sharing one sidecar process; copy-pasted open params from another session.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• initialize the ACPX sidecar first
• Existing Anthropic Environment does not match Paperclip's no
• Existing Anthropic Agent enables or omits the locked tools,
• managed_profile_not_found
• agentcore_profile_not_found

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