{"record":{"id":"af971e2246afd330","repo":"paperclipai/paperclip","slug":"createos-process-output-has-a-sequence-gap","errorCode":null,"errorMessage":"CreateOS process output has a sequence gap.","messagePattern":"CreateOS process output has a sequence gap\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/plugins/sandbox-providers/createos/src/execute.ts","lineNumber":156,"sourceCode":"      try {\n        response = await client.request(`${base}/${processId}/connect?after=${cursor}`, { signal });\n      } catch (error) {\n        if (error instanceof CreateosApiError && error.status === 410) {\n          throw new Error(\"CreateOS process output was evicted before it could be read.\");\n        }\n        if (signal.aborted || (error instanceof CreateosApiError && error.status < 500 && error.status !== 429)) throw error;\n        if (++reconnects > 3) throw new Error(\"CreateOS process output connection failed.\");\n        await delay(250, undefined, { signal });\n        continue;\n      }\n      try {\n        for await (const event of events(response)) {\n          if (event.type === \"heartbeat\") continue;\n          if (event.type === \"data\") {\n            const seq = event.seq;\n            if (typeof seq !== \"number\" || !Number.isSafeInteger(seq) || seq < 1) throw new Error(\"CreateOS process sequence is invalid.\");\n            if (seq <= cursor) continue;\n            if (seq !== cursor + 1) throw new Error(\"CreateOS process output has a sequence gap.\");\n            if ((event.stream !== \"stdout\" && event.stream !== \"stderr\") ||\n                typeof event.data_base64 !== \"string\" ||\n                !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(event.data_base64)) {\n              throw new Error(\"CreateOS process output is invalid.\");\n            }\n            output.write(event.stream, Buffer.from(event.data_base64, \"base64\"));\n            cursor = seq;\n          } else if (event.type === \"exit\") {\n            const exitCode = event.exit_code;\n            const exitSignal = event.signal;\n            if (!(typeof exitCode === \"number\" && Number.isInteger(exitCode)) &&\n                !(typeof exitSignal === \"string\" && /^SIG[A-Z0-9]+$/.test(exitSignal))) {\n              throw new Error(\"CreateOS process exit status is missing.\");\n            }\n            completed = true;\n            output.finish();\n            return {\n              exitCode: typeof exitCode === \"number\" ? exitCode : null,","sourceCodeStart":138,"sourceCodeEnd":174,"githubUrl":"https://github.com/paperclipai/paperclip/blob/3f1d897a7c018d76563a21c6e39c3c9b03933622/packages/plugins/sandbox-providers/createos/src/execute.ts#L138-L174","documentation":"A data event's seq skipped ahead of the expected cursor (seq !== cursor + 1 after filtering duplicates), indicating a lost frame between the server and client. Since output ordering/integrity cannot be guaranteed, the plugin fails closed rather than silently dropping bytes.","triggerScenarios":"The /connect?after=cursor stream resumes at a sequence beyond cursor+1 — e.g. the server rotated or trimmed buffered frames, a reconnect landed on a different replica, or the server skipped events under load.","commonSituations":"Reconnect after a network blip where the server no longer holds frames from the old cursor; CreateOS clustering/replica mismatch; server-side buffer trimming under memory pressure.","solutions":["Re-run the command; a fresh process starts at seq 1 and avoids the gap.","If reconnecting frequently, investigate network stability between client and CreateOS host.","Check server-side buffering/retention settings and replica consistency for the /connect endpoint.","Do not reconnect past the gap: the plugin intentionally refuses to resume beyond missing data."],"exampleFix":"// before\nconnect(after=41) -> first event seq 43   // frame 42 lost -> gap\n// after\nre-run execute() on a fresh process       // seq restarts at 1, no gap","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try { await execute(client, params, signal); }\ncatch (e) {\n  if (e instanceof Error && e.message === \"CreateOS process output has a sequence gap.\") {\n    // lost frame: re-run on a fresh process; never resume the gapped stream\n  } else throw e;\n}","preventionTips":["Keep the network path to CreateOS stable; investigate frequent reconnects.","Verify server-side buffering retains the full window your reconnect latency requires.","Avoid clustered/replica setups where /connect can hit different replicas.","Re-run instead of trying to skip past gaps."],"tags":["protocol","streaming","sequence"],"backgroundTag":"unexpected-api-response-shape","analyzedSha":"3f1d897a7c018d76563a21c6e39c3c9b03933622","analyzedAt":"2026-09-18T08:03:59.046Z","contentChangedAt":"2026-09-18T08:03:59.046Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}