paperclipai/paperclip · error

${payload?.error ?? `Failed to request restart (${res.status

Error message

${payload?.error ?? `Failed to request restart (${res.status})`}

What it means

The health API's requestDevServerRestart throws this Error when the POST to /api/health/dev-server/restart returns non-OK. It mirrors the other health error paths: prefer the server's `error` string, fall back to a status-embedded message, and consult tenant session recovery first.

Source

Thrown at ui/src/api/health.ts:71

    if (!res.ok) {
      const payload = await res.json().catch(() => null) as { error?: string } | null;
      const recovery = tenantSessionRecovery.recoverIfNeeded(res.status, payload);
      if (recovery) return recovery;
      throw new Error(payload?.error ?? `Failed to load health (${res.status})`);
    }
    return res.json();
  },
  requestDevServerRestart: async (): Promise<void> => {
    const res = await fetch("/api/health/dev-server/restart", {
      method: "POST",
      credentials: "include",
      headers: { Accept: "application/json" },
    });
    if (!res.ok) {
      const payload = await res.json().catch(() => null) as { error?: string } | null;
      const recovery = tenantSessionRecovery.recoverIfNeeded(res.status, payload);
      if (recovery) return recovery;
      throw new Error(payload?.error ?? `Failed to request restart (${res.status})`);
    }
  },
};

View on GitHub (pinned to 01ad858492)

Solutions

1. Confirm the app is running in dev mode where the restart route exists
2. Check server logs for the restart handler's error
3. Retry after the dev server has fully started
4. Handle non-JSON responses so the fallback status message is shown

Example fix

// before
throw new Error(payload?.error ?? `Failed to request restart (${res.status})`);
// after
if (res.status === 404) throw new Error('Dev-server restart is only available in development mode.');
throw new Error(payload?.error ?? `Failed to request restart (${res.status})`);

const isDev = import.meta.env.DEV; if (!isDev) return; // restart route only exists in dev

function isRestartError(p: unknown): p is { error: string } { return typeof p === 'object' && p !== null && typeof (p as any).error === 'string'; }

try { await healthApi.requestDevServerRestart(); } catch (e) { if (/restart/i.test(e.message)) showToast('Restart unavailable: ' + e.message); else throw e; }

When it happens

Trigger: POST dev-server restart endpoint returns 4xx/5xx, e.g. restart not permitted, dev server not running, or route unavailable in production builds.

Common situations: Clicking 'restart dev server' in the UI while the server is compiled/production mode (route disabled), dev process crashed and cannot accept the POST, permission denied by middleware.

Understand the failure class

Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.

Related errors

• OpenCode API ${path} request failed: ${redact(String(error),
• OpenCode API ${path} returned HTTP ${response.status}: ${red
• Discord ${operation} failed (HTTP ${response.status}${code ?
• ${(payload as { error?: string } | null)?.error ?? `Failed t
• ${(errorBody as { error?: string } | null)?.error ?? `Reques

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-09-10). Data as JSON: /api/errors/36eb1f7628655e36. Report an issue: GitHub.