paperclipai/paperclip · error · Error

${MANAGED_CONFIG_ENV_KEY} ${detail}

Error message

${MANAGED_CONFIG_ENV_KEY} ${detail}

What it means

fail() sentinel used by parseManagedConfigEnv: the PAPERCLIP_MANAGED_CONFIG env document violated a parsing rule (bad JSON, unknown feature key, bad shape), and `detail` describes the specific violation. Centralizes all managed-config startup errors under one env-key-prefixed message.

Source

Thrown at server/src/services/managed-config.ts:122

/**
 * The set of feature keys a managed-config document may target: the boolean
 * flag keys of `instanceExperimentalSettingsSchema`. The schema is the
 * manifest — server-managed bookkeeping fields (activation cutoffs, lookback
 * hours) are not booleans and are excluded by construction.
 */
export function managedFeatureKeySet(): ReadonlySet<string> {
  if (!cachedFeatureKeys) {
    const defaults = instanceExperimentalSettingsSchema.parse({}) as Record<string, unknown>;
    cachedFeatureKeys = new Set(
      Object.keys(defaults).filter((key) => typeof defaults[key] === "boolean"),
    );
  }
  return cachedFeatureKeys;
}

function fail(detail: string): never {
  throw new Error(`${MANAGED_CONFIG_ENV_KEY} ${detail}`);
}

function isPlainObject(value: unknown): value is Record<string, unknown> {
  return typeof value === "object" && value !== null && !Array.isArray(value);
}

function describeJsonValue(value: unknown): string {
  if (value === null) return "null";
  if (Array.isArray(value)) return "an array";
  return `${JSON.stringify(value)}`;
}

/**
 * Parse `PAPERCLIP_MANAGED_CONFIG` from a raw env map. Returns null only when
 * the variable is absent (self-hosted). Throws with a precise error on a
 * present-but-blank value or any malformed document so a cloud instance fails
 * to start (fail closed).
 */

View on GitHub (pinned to 120ae5428f)

Solutions

1. Fix the managed config issue described in the detail, then restart.

When it happens

Trigger: Thrown at server/src/services/managed-config.ts:122 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/cc87abc3a5b7c76e. Report an issue: GitHub.