{"record":{"id":"91373a9f4514eba9","repo":"paperclipai/paperclip","slug":"initialize-the-acpx-sidecar-first","errorCode":null,"errorMessage":"initialize the ACPX sidecar first","messagePattern":"initialize the ACPX sidecar first","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/paperclip-runner/src/cli/acpx-runtime-sidecar.ts","lineNumber":247,"sourceCode":"        persistentSessions: true,\n        exactModelVerification: true,\n        permissions: \"runner_policy\",\n        semanticTools: \"runner_bridge\",\n        structuredInput: \"paperclip.question_set.v1\",\n      },\n    };\n  }\n  if (request.command === \"session.open\") {\n    if (\n      hasSidecarSessionOwnership(\n        host,\n        activeHostCleanup,\n        failedAdmissionCleanup,\n      )\n    ) {\n      throw new Error(\"ACPX sidecar already owns a session or its cleanup\");\n    }\n    if (!initializedModel) throw new Error(\"initialize the ACPX sidecar first\");\n    const params = parseOpenParams(request.params);\n    if (\n      params.agent !== initializedAgent ||\n      params.model !== initializedModel\n    ) {\n      throw new Error(\"ACPX session profile differs from its initialization\");\n    }\n    const openedHost = await AcpxRuntimeHost.open(\n      {\n        runtimeDirectory: params.runtimeDirectory,\n        normalizedSessionId: params.normalizedSessionId,\n        workingDirectory: params.workingDirectory,\n        agent: params.agent,\n        model: params.model,\n        permissionMode: params.permissionMode,\n        systemInstructions: params.systemInstructions,\n        environment: process.env,\n        expectedIdentity: params.expectedIdentity,","sourceCodeStart":229,"sourceCodeEnd":265,"githubUrl":"https://github.com/paperclipai/paperclip/blob/01ad8584922b5d85292b1723cae71fa0d9b07a19/packages/paperclip-runner/src/cli/acpx-runtime-sidecar.ts#L229-L265","documentation":"The ACPX runtime sidecar's dispatch() requires that the sidecar has been initialized with an agent/model profile before processing open requests. If initializedModel is not set, dispatch throws \"initialize the ACPX sidecar first\" because there is no profile against which session opens can be validated and no host configuration to open with.","triggerScenarios":"Sending an open (or other session) JSON-RPC request to the sidecar before the initialize request; a lost/restarted sidecar process whose initialization state was wiped while the client kept its old connection; racing the open request ahead of initialization.","commonSituations":"Client bug skipping the initialize handshake; sidecar crash-recovery reusing a stale client; tests or scripts invoking dispatch directly without setup; transport reconnect that spawned a fresh sidecar.","solutions":["Send the initialize request (with agent/model) before any open/session requests","Re-initialize the sidecar after restart or reconnect before resuming dispatch","Add a client-side readiness gate that blocks requests until init is acknowledged","Inspect sidecar startup logs to confirm initialization completed"],"exampleFix":"// before\nsidecar.dispatch({ method: 'session/open', params });\n// after\nif (!sidecar.isInitialized()) {\n  await sidecar.dispatch({ method: 'initialize', params: { agent, model } });\n}\nsidecar.dispatch({ method: 'session/open', params });","handlingStrategy":"validation","validationCode":"if (!sidecar.isInitialized()) await sidecar.initialize({ agent, model });","typeGuard":"const sidecarReady = (s: { initializedModel?: string | null }): s is { initializedModel: string } => typeof s.initializedModel === 'string' && s.initializedModel.length > 0;","tryCatchPattern":"try { sidecar.dispatch(request); } catch (e) { if (e.message === 'initialize the ACPX sidecar first') { await sidecar.initialize(initParams); return sidecar.dispatch(request); } throw e; }","preventionTips":["Always run the initialize handshake before session requests","Re-initialize after sidecar restart or transport reconnect","Block outbound requests until init is acknowledged client-side"],"tags":["initialization","sidecar","acpx"],"backgroundTag":"invalid-state-transition","analyzedSha":"01ad8584922b5d85292b1723cae71fa0d9b07a19","analyzedAt":"2026-09-10T03:14:50.855Z","contentChangedAt":"2026-09-10T03:14:50.855Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}