paperclipai/paperclip · error

CreateOS process sequence is invalid.

Error message

CreateOS process sequence is invalid.

What it means

A `data` event on the process output stream carried a `seq` that is not a positive safe integer. The plugin validates sequence numbers strictly to guarantee ordered, gap-free output; a malformed seq means the server is violating the protocol, so it fails closed instead of guessing.

Solutions

1. Capture the raw frame and confirm the seq field's actual value/type against the expected protocol.
2. Pin/align the CreateOS service version with the plugin's expected protocol.
3. Check for intermediaries (proxies, transforms) altering event JSON in transit.
4. Retry once to rule out a transient glitch; persistent failures indicate server-side protocol bugs — report upstream.
5. Treat the run as failed and re-execute; never skip or fabricate sequence numbers.

Example fix

// before (server bug)
{ "type": "data", "stream": "stdout", "data_base64": "aGk=" }        // seq missing
// after
{ "type": "data", "seq": 7, "stream": "stdout", "data_base64": "aGk=" }

function hasValidSeq(e: unknown): e is { type: "data"; seq: number } {
  return typeof e === "object" && e !== null && "seq" in e
    && typeof (e as any).seq === "number" && Number.isSafeInteger((e as any).seq) && (e as any).seq >= 1;
}

try { await execute(client, params, signal); }
catch (e) {
  if (e instanceof Error && e.message === "CreateOS process sequence is invalid.") {
    // protocol violation: capture diagnostics, re-run once, then escalate
  } else throw e;
}

When it happens

Trigger: CreateOS (or an intermediary rewriting the stream) emits a data event with a missing/non-numeric seq, a float, 0, a negative value, or an unsafe integer beyond Number.MAX_SAFE_INTEGER.

Common situations: Protocol drift between plugin and a newer/older CreateOS service; a bug or memory corruption server-side; a man-in-the-middle or proxy rewriting event payloads.

Understand the failure class

Background: "invalid response format", "malformed payload", "missing data field": when an API returns 200 but the response shape is wrong — this error's family across 23 libraries.

Related errors

• CreateOS process output has a sequence gap.
• CreateOS process exit status is missing.
• CreateOS process output is invalid.
• CreateOS returned an invalid process frame.
• Photon attachment header is missing

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

Appendix: source

Thrown at packages/plugins/sandbox-providers/createos/src/execute.ts:154

      signal.throwIfAborted();
      let response: Response;
      try {
        response = await client.request(`${base}/${processId}/connect?after=${cursor}`, { signal });
      } catch (error) {
        if (error instanceof CreateosApiError && error.status === 410) {
          throw new Error("CreateOS process output was evicted before it could be read.");
        }
        if (signal.aborted || (error instanceof CreateosApiError && error.status < 500 && error.status !== 429)) throw error;
        if (++reconnects > 3) throw new Error("CreateOS process output connection failed.");
        await delay(250, undefined, { signal });
        continue;
      }
      try {
        for await (const event of events(response)) {
          if (event.type === "heartbeat") continue;
          if (event.type === "data") {
            const seq = event.seq;
            if (typeof seq !== "number" || !Number.isSafeInteger(seq) || seq < 1) throw new Error("CreateOS process sequence is invalid.");
            if (seq <= cursor) continue;
            if (seq !== cursor + 1) throw new Error("CreateOS process output has a sequence gap.");
            if ((event.stream !== "stdout" && event.stream !== "stderr") ||
                typeof event.data_base64 !== "string" ||
                !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(event.data_base64)) {
              throw new Error("CreateOS process output is invalid.");
            }
            output.write(event.stream, Buffer.from(event.data_base64, "base64"));
            cursor = seq;
          } else if (event.type === "exit") {
            const exitCode = event.exit_code;
            const exitSignal = event.signal;
            if (!(typeof exitCode === "number" && Number.isInteger(exitCode)) &&
                !(typeof exitSignal === "string" && /^SIG[A-Z0-9]+$/.test(exitSignal))) {
              throw new Error("CreateOS process exit status is missing.");
            }
            completed = true;
            output.finish();

View on GitHub (pinned to 3f1d897a7c)