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.

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
• ACPX profile requires exact model ; received
• ACPX runtime executable changed while it was verified
• ACPX runtime executable could not be opened as a no-follow…
• ACPX runtime executable digest mismatch

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

Appendix: source

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

    };
  }
  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,
        runtimeContext: params.runtimeContext,
        environment: process.env,
        expectedIdentity: params.expectedIdentity,
        semanticTools: {
          tools: params.tools,
          handler: waitForTool,
        },
        onGoalUpdate: (goal) => {

View on GitHub (pinned to 3f1d897a7c)