paperclipai/paperclip · error

ACPX sidecar runtime context must be pre-materialized

Error message

ACPX sidecar runtime context must be pre-materialized

What it means

The ACPX sidecar expects its runtime context to be materialized (written to disk / pre-created) before the sidecar opens; it refuses inline runtimeContext payloads in open params. Passing a non-null runtimeContext is treated as a caller contract violation.

Source

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

  const bytes = Buffer.from(redacted);
  return {
    output: bytes
      .subarray(Math.max(0, bytes.length - 64 * 1024))
      .toString("utf8"),
    outputBytes: bytes.length,
    outputTruncated: bytes.length > 64 * 1024,
    outputDigest: `sha256:${createHash("sha256").update(bytes).digest("hex")}`,
  };
}

function parseOpenParams(
  value: Record<string, unknown>,
): AcpxSidecarOpenParams {
  const agent = requireQualifiedAgent(value.agent);
  const model = requiredText(value.model, "model");
  resolveQualifiedAcpxProfile(agent, model);
  if (value.runtimeContext !== undefined && value.runtimeContext !== null) {
    throw new Error("ACPX sidecar runtime context must be pre-materialized");
  }
  if (
    value.providerSessionKey !== undefined &&
    value.providerSessionKey !== null
  ) {
    throw new Error(
      "ACPX replacement provider sessions are not available in this release",
    );
  }
  return {
    runtimeDirectory: requiredText(value.runtimeDirectory, "runtimeDirectory"),
    normalizedSessionId: boundedIdentity(
      value.normalizedSessionId,
      "normalizedSessionId",
    ),
    workingDirectory: requiredText(value.workingDirectory, "workingDirectory"),
    agent,
    model,

View on GitHub (pinned to 01ad858492)

Solutions

1. Pre-materialize the runtime context (write it out via the designated mechanism) and omit runtimeContext from the open params
2. Set runtimeContext to undefined/null in the params you pass
3. Update the calling code to the current sidecar open contract

Example fix

// before
openSidecar({ agent: 'codex', model: 'gpt-5', runtimeContext: ctx });
// after
await materializeRuntimeContext(ctx);
openSidecar({ agent: 'codex', model: 'gpt-5' });

if (params.runtimeContext !== undefined && params.runtimeContext !== null) throw new Error('materialize runtime context before opening sidecar');

function hasNoInlineRuntimeContext(p: { runtimeContext?: unknown }): p is Omit<typeof p, 'runtimeContext'> {
  return p.runtimeContext === undefined || p.runtimeContext === null;
}

try { await openSidecar(params); }
catch (e) { if (String(e.message).includes('pre-materialized')) { await materializeRuntimeContext(params.runtimeContext); delete params.runtimeContext; await openSidecar(params); } else throw e; }

When it happens

Trigger: Calling the open-params parser (from record value) with value.runtimeContext set to any non-undefined, non-null value.

Common situations: Older callers embedding runtime context directly in open params; a serialization layer forwarding the whole parent context object instead of the pre-materialized path/ID.

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

• ${path} must be an object
• ${path} must be a non-empty string
• ${path} must be a positive safe integer
• ${path} must be a positive finite number
• request.managedProfile.betaVersion is not qualified

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