What causes "CreateOS command probe failed." in paperclipai/paperclip?

Re-run the probe; transient CreateOS slowness is the most common cause (command timeout rather than genuine failure).

CreateOS command probe failed.

Error message

CreateOS command probe failed.

What it means

Thrown by onEnvironmentProbe when the plugin's readiness probe fails. The probe acquires a temporary lease, runs '/bin/echo paperclip-createos-ready' in the sandbox, and requires the command to exit 0, not time out, and echo the exact marker on stdout. Any deviation (sandbox never became ready, command timed out, wrong output) raises this error; the underlying cause is discarded in favor of this fixed message.

Solutions

Re-run the probe; transient CreateOS slowness is the most common cause (command timeout rather than genuine failure).
Increase config.timeoutMs so the probe command has enough budget on cold starts.
Check CreateOS API health/logs for the sandbox — a non-zero exit or missing marker usually indicates an image or init problem.
If probes consistently fail, verify the sandbox image supports /bin/echo and that shell init does not swallow stdout.

Example fix

// before: default timeout too small for cold starts
const config = { shape: 'small', region: 'us-1', timeoutMs: 5000 };
// after
const config = { shape: 'small', region: 'us-1', timeoutMs: 30000 };

Defensive patterns

Strategy: retry

Validate before calling

// Pre-flight config sanity before probing
function probeConfigOk(config: { timeoutMs: number }): boolean {
  return Number.isFinite(config.timeoutMs) && config.timeoutMs >= 10000;
}

Type guard

function isProbeFailure(e: unknown): boolean {
  return e instanceof Error && e.message === 'CreateOS command probe failed.';
}

Try / catch

const probe = await plugin.onEnvironmentProbe(params); // returns {ok,summary}, rarely throws
if (!probe.ok) {
  await sleep(2000);
  const retry = await plugin.onEnvironmentProbe(params);
  if (!retry.ok) throw new Error(`CreateOS probe failed twice: ${retry.summary}`);
}

Prevention

Set timeoutMs generously (>=30s) to absorb sandbox cold starts
Retry the probe once or twice before declaring the provider unhealthy
Verify the sandbox image supports /bin/echo and preserves stdout
Monitor CreateOS service health; cluster-wide probe failures indicate provider outage, not config

When it happens

Trigger: Calling onEnvironmentProbe (environment health check / plugin validation) when: sandbox creation succeeds but command execution times out (result.timedOut), the echo process exits non-zero, or stdout does not contain 'paperclip-createos-ready' (e.g. the sandbox's shell/init mangled the output or a different process captured stdout).

Common situations: CreateOS service degraded or overloaded so commands queue past timeoutMs; sandbox image without a working /bin/echo or broken shell init; overly small timeoutMs in config; region/shape misprovisioning causing slow cold starts.

Understand the failure class

Background: 'Something went wrong' / 'Request failed (500)' / 'HTTP error! status: 404' — what failed HTTP requests actually mean and how to find the real cause — this error's family across 28 libraries.

Related errors

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

Appendix: source

Thrown at packages/plugins/sandbox-providers/createos/src/plugin.ts:142

      closing.delete(scope);
    }
  }

  return definePlugin({
    async setup(context) { ctx = context; ctx.logger.info("CreateOS sandbox provider ready"); },
    async onHealth() { return { status: "ok", message: "CreateOS provider loaded; probe an environment to check connectivity." }; },
    async onEnvironmentValidateConfig(params) {
      try { return { ok: true, normalizedConfig: { ...parseConfig(params.config) } }; }
      catch (error) { return { ok: false, errors: [error instanceof Error ? error.message : "Invalid CreateOS configuration."] }; }
    },
    async onEnvironmentProbe(params) {
      let lease: PluginEnvironmentLease | null = null;
      try {
        lease = await acquire({ ...params, runId: "probe" });
        const result = await execute(new CreateosClient(parseConfig(params.config)), {
          ...params, lease, command: "/bin/echo", args: ["paperclip-createos-ready"], cwd: CWD,
        }, AbortSignal.timeout(parseConfig(params.config).timeoutMs));
        if (result.timedOut || result.exitCode !== 0 || !result.stdout.includes("paperclip-createos-ready")) throw new Error("CreateOS command probe failed.");
        return { ok: true, summary: "CreateOS sandbox creation and command execution succeeded." };
      } catch (error) {
        return { ok: false, summary: error instanceof Error ? error.message : "CreateOS probe failed." };
      } finally {
        // Never leave a reusable probe sandbox behind or hide deletion failure.
        if (lease?.providerLeaseId) await new CreateosClient(parseConfig(params.config)).destroySandbox(lease.providerLeaseId);
      }
    },
    onEnvironmentAcquireLease: acquire,
    async onEnvironmentResumeLease(params) {
      if (!metadataMatches(params, params.leaseMetadata)) throw new Error("CreateOS lease does not belong to this environment.");
      const scope = key(params, params.providerLeaseId);
      if (closing.has(scope) || unconfirmedCleanup.has(scope)) throw new Error("CreateOS lease cleanup must finish before resume.");
      const marker = params.leaseMetadata?.marker;
      if (typeof marker !== "string" || !/^[0-9a-f-]{36}$/.test(marker)) return { providerLeaseId: null, metadata: { expired: true } };
      const config = parseConfig(params.config);
      if (params.leaseMetadata?.shape !== config.shape || params.leaseMetadata.rootfs !== config.rootfs || params.leaseMetadata.region !== config.region) {
        return { providerLeaseId: null, metadata: { expired: true } };

View on GitHub (pinned to 3f1d897a7c)