paperclipai/paperclip · error · Error

PAPERCLIP_EXECUTION_MODE and the PAPERCLIP_MANAGED_CONFIG "e

Error message

PAPERCLIP_EXECUTION_MODE and the PAPERCLIP_MANAGED_CONFIG "environments" section are mutually exclusive: both manage the single instance sandbox environment

What it means

Mutual-exclusion guard in applyManagedEnvironments: both PAPERCLIP_EXECUTION_MODE=kubernetes bootstrap and a managed-config 'environments' section are configured. Both claim ownership of the single managed sandbox environment row; startup refuses rather than letting bootstrap ordering pick a winner.

Source

Thrown at server/src/services/managed-environments.ts:187

        );
      }
    } catch (err) {
      logger.error(
        { err },
        "failed to revert the stamped managed sandbox instance default (degraded: stale default until the next boot)",
      );
    }
  }

  if (managedConfig.environments.length === 0) return null;

  // The forced-execution-mode bootstrap (`PAPERCLIP_EXECUTION_MODE=kubernetes`)
  // and this one both own the single Paperclip-managed sandbox row
  // (`environments_managed_sandbox_idx`). Configuring both is contradictory;
  // refuse startup rather than let bootstrap ordering pick a winner.
  const env = opts.env ?? process.env;
  if (parseExecutionPolicyBootstrapEnv(env)) {
    throw new Error(
      `PAPERCLIP_EXECUTION_MODE and the PAPERCLIP_MANAGED_CONFIG "environments" section are mutually exclusive: both manage the single instance sandbox environment`,
    );
  }

  // The heartbeat resumes queued runs right after this bootstrap step, and
  // lease acquisition fails hard on a provider whose plugin is missing or not
  // ready. Wait for the bundled-plugin startup pass to finish, then refuse to
  // ensure (and in particular to re-activate) a row whose provider driver did
  // not come up — a degraded boot without the row beats an active environment
  // that fails every lease until the plugin recovers.
  await opts.pluginsReady;

  const resolveDriver = opts.resolveSandboxProviderDriver ?? resolvePluginSandboxProviderDriverByKey;

  /**
   * Point the instance default at the managed sandbox row when no
   * deliberate choice stands in the way: an unset default, a default on
   * the (hidden-under-this-mode) local row, or a dangling reference all

View on GitHub (pinned to 120ae5428f)

Solutions

1. Use either PAPERCLIP_EXECUTION_MODE or the PAPERCLIP_MANAGED_CONFIG "environments" section, not both.

When it happens

Trigger: Thrown at server/src/services/managed-environments.ts:187 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of paperclipai/paperclip@120ae5428f (2026-08-18). Data as JSON: /api/errors/7b1a84ce2b939519. Report an issue: GitHub.