paperclipai/paperclip · error

PAPERCLIP_API_URL is required to deliver managed runtime MCP

Error message

PAPERCLIP_API_URL is required to deliver managed runtime MCP servers

What it means

paperclipApiBaseUrl() needs the base URL of this Paperclip API instance to build managed runtime MCP gateway endpoints, and PAPERCLIP_API_URL is unset or empty. Managed MCP delivery cannot construct gateway URLs without it, so it throws immediately.

Source

Thrown at server/src/services/heartbeat.ts:3433

   * additional project. The array is empty unless the multi-project workspace-sync flag is on
   * ({@link isMultiProjectWorkspaceSyncEnabled}); with the flag off the run resolves the anchor
   * workspace only, exactly as before.
   */
  additionalWorkspaces: ResolvedAdditionalWorkspace[];
  /**
   * Structured record of every referenced project that the run dropped or failed, paired with the
   * layer that dropped it. Run preparation reads this to emit the requested-vs-synced observability
   * log. The human-readable form of each drop already rides {@link ResolvedWorkspaceForRun.warnings}.
   */
  referencedProjectFailures: ReferencedProjectFailure[];
};

/** The anchor workspace shape, before the additional referenced workspaces are attached. */
type ResolvedAnchorWorkspaceForRun = Omit<
  ResolvedWorkspaceForRun,
  "additionalWorkspaces" | "referencedProjectFailures"
>;

/**
 * Assemble the run warnings for the agent-home fallback when a project has workspaces but none
 * produced a usable cwd. Materialization failures (for example a failed managed clone) take
 * priority over the generic "no local cwd configured" note, which previously masked them.
 */
export function buildAnchorFallbackWorkspaceNotes(input: {
  fallbackCwd: string;
  preferredWorkspaceWarning: string | null;
  materializationFailures: WorkspaceMaterializationFailure[];
  missingProjectCwds: string[];
  hasConfiguredProjectCwd: boolean;
}): string[] {
  const warnings: string[] = [];
  if (input.preferredWorkspaceWarning) {
    warnings.push(input.preferredWorkspaceWarning);
  }
  if (input.materializationFailures.length > 0) {
    const first = input.materializationFailures[0];

View on GitHub (pinned to 01ad858492)

Solutions

  1. Set PAPERCLIP_API_URL to this instance's reachable API URL so managed runtime MCP servers can be delivered.
Defensive patterns

Strategy: validation

When it happens

Trigger: Thrown at server/src/services/heartbeat.ts:3264 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-08-18). Data as JSON: /api/errors/f2ca4b402d2caa5d. Report an issue: GitHub.