paperclipai/paperclip · error · Error

PAPERCLIP_DECISION_SIGNING_SECRET must be at least ${MIN_SEC

Error message

PAPERCLIP_DECISION_SIGNING_SECRET must be at least ${MIN_SECRET_LENGTH} characters when set (unset it to use an auto-generated key)

What it means

Secret-quality guard in resolveDecisionSigningSecret: PAPERCLIP_DECISION_SIGNING_SECRET is set but shorter than the 32-character minimum. Weak HMAC keys would undermine decision-spec signing, so the operator must supply a longer value or unset the variable to use the auto-generated key file.

Source

Thrown at server/src/services/decision-signing.ts:127

      return generated;
    } catch (error) {
      if (!isAlreadyExists(error)) throw error;
      return readGeneratedSecret(keyPath);
    }
  } finally {
    try {
      unlinkSync(temporaryPath);
    } catch (error) {
      if (!isNotFound(error)) throw error;
    }
  }
}

export function resolveDecisionSigningSecret(): string {
  const fromEnv = process.env.PAPERCLIP_DECISION_SIGNING_SECRET?.trim();
  if (fromEnv) {
    if (fromEnv.length < MIN_SECRET_LENGTH) {
      throw new Error(
        `PAPERCLIP_DECISION_SIGNING_SECRET must be at least ${MIN_SECRET_LENGTH} characters when set (unset it to use an auto-generated key)`,
      );
    }
    return fromEnv;
  }
  return loadOrCreateGeneratedSecret();
}

/**
 * Startup guard: resolves the signing secret once so an invalid explicit
 * PAPERCLIP_DECISION_SIGNING_SECRET fails fast and the generated key file is
 * materialized before the first decision write. A missing env var is not an
 * error — the secret is auto-generated and persisted per instance.
 */
export function ensureDecisionSigningSecret() {
  resolveDecisionSigningSecret();
}

View on GitHub (pinned to 120ae5428f)

Solutions

1. Set PAPERCLIP_DECISION_SIGNING_SECRET to a value of at least the minimum length, or unset it to use an auto-generated key.

When it happens

Trigger: Thrown at server/src/services/decision-signing.ts:127 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/967c1f4dc0dc1bd4. Report an issue: GitHub.