paperclipai/paperclip · error · Error

Invalid PAPERCLIP_INSTANCE_ID

Error message

Invalid PAPERCLIP_INSTANCE_ID '${instanceId}'.

What it means

Error "Invalid PAPERCLIP_INSTANCE_ID '${instanceId}'." thrown in paperclipai/paperclip.

Solutions

1. Set PAPERCLIP_INSTANCE_ID to a valid instance id value.

When it happens

Trigger: Thrown at packages/adapter-utils/src/server-utils.ts:154 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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

Appendix: source

Thrown at packages/adapter-utils/src/server-utils.ts:169

const PATH_SEGMENT_RE = /^[a-zA-Z0-9_-]+$/;
const SENSITIVE_ENV_KEY =
  /(key|token|secret|password|passwd|authorization|cookie)/i;
const REDACTED_LOG_VALUE = "***REDACTED***";

// PAPERCLIP_* is the reserved runtime namespace: these vars are generated by
// Paperclip per run (identity, wake, workspace, API access). Adapter/user
// config env must never override them.
export function isPaperclipRuntimeEnvKey(key: string): boolean {
  return key.startsWith("PAPERCLIP_");
}

// PAPERCLIP_API_KEY is never accepted from adapter/user config env: the
// harness-minted run token is the only source of Paperclip API identity.
// Other PAPERCLIP_*-named config keys are allowed as long as Paperclip has
// not assigned the same key for the run (runtime vars always win).
export function isForbiddenConfigEnvKey(key: string): boolean {
  return key === "PAPERCLIP_API_KEY";
}
const PAPERCLIP_SKILL_ROOT_RELATIVE_CANDIDATES = [
  "../../skills",
  "../../../../../skills",
];
const MATERIALIZED_SKILL_SENTINEL = ".paperclip-materialized-skill.json";
const MATERIALIZED_SKILL_LOCK_OWNER = "owner.json";
const MATERIALIZED_SKILL_LOCK_STALE_MS = 30_000;

function expandHomePrefix(value: string): string {
  if (value === "~") return os.homedir();
  if (value.startsWith("~/")) return path.resolve(os.homedir(), value.slice(2));
  return value;
}

export function resolvePaperclipInstanceRootForAdapter(
  input: {
    homeDir?: string;
    instanceId?: string;

View on GitHub (pinned to 3f1d897a7c)