paperclipai/paperclip · error

CreateOS returned an unknown process event.

Error message

CreateOS returned an unknown process event.

What it means

execute() consumes a stream of typed process events (exit, output, error). If an event arrives whose type matches none of the known variants, the provider fails closed with this message rather than guessing. It guards against protocol drift between the client and the CreateOS server.

Solutions

1. Upgrade the @paperclipai sandbox-providers createos package (and server) so both sides agree on the event schema.
2. Log the raw event (JSON.stringify(event)) to identify the unknown type before failing.
3. Verify no intermediary proxy is modifying or fragmenting the SSE/stream response.
4. Check for known protocol changes in CreateOS release notes.

Example fix

// before
} else {
  throw new Error("CreateOS returned an unknown process event.");
}
// after
} else {
  logger.warn("unknown createos event", event);
  throw new Error(`CreateOS returned an unknown process event: ${JSON.stringify(event)}`);
}

function isKnownProcessEvent(e) {
  return ["exit", "output", "error"].includes(e?.type);
}

try {
  await execute(lease, cmd, { signal });
} catch (e) {
  if (e.message === "CreateOS returned an unknown process event.") {
    reportProtocolMismatch(e); // upgrade client/server
  }
  throw e;
}

When it happens

Trigger: The CreateOS API emits a new or malformed event type not handled by the switch/else-if chain in execute(); a proxy or middleware rewrites the stream payload; a version mismatch between client and server introduces an event variant this client does not know.

Common situations: Running an older plugin against a newer CreateOS server that added event types; a gateway injecting keep-alive frames parsed as events; corrupted stream framing producing junk events.

Related errors

• Codex turn response omitted turn.id
• CreateOS file download has no body.
• CreateOS process stream reported an error.
• CreateOS returned an empty process stream.
• A sandbox command is required.

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

Appendix: source

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

            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();
            return {
              exitCode: typeof exitCode === "number" ? exitCode : null,
              signal: typeof exitSignal === "string" ? exitSignal : null,
              timedOut: false, stdout: output.stdout, stderr: output.stderr,
              metadata: { processId, outputTruncated: output.truncated },
            };
          } else if (event.type === "error") {
            throw new Error(event.error === "output_offset_expired"
              ? "CreateOS process output was evicted before it could be read."
              : "CreateOS process stream reported an error.");
          } else {
            throw new Error("CreateOS returned an unknown process event.");
          }
        }
      } catch (error) {
        // Network read failures can resume from the last accepted sequence.
        // Protocol errors must fail closed rather than reconnect past bad data.
        if (!(error instanceof TypeError) || signal.aborted) throw error;
      }
      if (++reconnects > 3) throw new Error("CreateOS process stream ended without an exit status.");
      await delay(250, undefined, { signal });
    }
  } catch (error) {
    if (creationMayHaveSucceeded && !processId) {
      throw new CreateosCleanupError("CreateOS process creation could not be confirmed; destroy the lease before reusing it.");
    }
    if (signal.aborted && signal.reason?.name === "TimeoutError") {
      output.finish();
      return {
        exitCode: null, timedOut: true, stdout: output.stdout, stderr: output.stderr,

View on GitHub (pinned to 3f1d897a7c)