gildas-lormeau/SingleFile · error · Error

MCP server error: ${response.status} ${response.statusText}

Error message

MCP server error: ${response.status} ${response.statusText}

What it means

checkFileExists performs a POST to the MCP server and throws "MCP server error: <status> <statusText>" when the HTTP response is not ok (response.ok is false, i.e. status outside 200-299). This is a transport-level failure — the server rejected the request before any JSON-RPC/tool result could be evaluated.

Source

Thrown at src/lib/mcp/mcp.js:144

            }
        }
    };

    const headers = {
        [CONTENT_TYPE_HEADER]: JSON_CONTENT_TYPE,
        "Accept": "application/json, text/event-stream"
    };
    if (authToken) {
        headers.Authorization = `Bearer ${authToken}`;
    }
    const response = await fetch(serverUrl, {
        method: "POST",
        headers,
        body: JSON.stringify(requestBody),
        signal
    });
    if (!response.ok) {
        throw new Error(`MCP server error: ${response.status} ${response.statusText}`);
    }
    const data = await response.json();
    if (data.error) {
        return { exists: false };
    }
    if (data.result && data.result.isError) {
        return { exists: false };
    }
    if (data.result) {
        return { exists: true };
    }
    return { exists: false };
}

async function writeFile(serverUrl, authToken, path, content, signal, getRequestId) {
    const requestBody = {
        jsonrpc: MCP_JSONRPC_VERSION,
        id: getRequestId(),

View on GitHub (pinned to 517fb7c5cf)

Solutions

  1. Log response.status/statusText and, if possible, response.text() for the server's error detail.
  2. Re-authenticate: refresh authToken and confirm it is sent in the expected header.
  3. Verify serverUrl and the tool/endpoint name against the server's current configuration.
  4. If status is 5xx, retry with backoff — it is likely transient server unavailability.
  5. Confirm the MCP server is running and reachable (curl/health check) before calling.

Example fix

// before
await checkFileExists(serverUrl, token, path); // Error: MCP server error: 401 Unauthorized
// after
try {
  await checkFileExists(serverUrl, token, path);
} catch (e) {
  if (/MCP server error: (401|403)/.test(e.message)) {
    token = await refreshAuthToken();
    return checkFileExists(serverUrl, token, path);
  }
  throw e;
}
Defensive patterns

Strategy: retry

Validate before calling

async function serverReachable(serverUrl) {
  try { const r = await fetch(serverUrl, { method: "OPTIONS" }); return r.status < 500; }
  catch { return false; }
}
if (!token) throw new Error("authToken required before checkFileExists");

Try / catch

try { await checkFileExists(serverUrl, token, path); }
catch (e) {
  const m = /MCP server error: (\d+)/.exec(e.message);
  const status = m && Number(m[1]);
  if (status >= 500) return retryWithBackoff(() => checkFileExists(serverUrl, token, path));
  if (status === 401 || status === 403) return reauthThenRetry();
  throw e;
}

Prevention

When it happens

Trigger: Auth token missing/expired → 401; token lacking access to the target → 403; wrong serverUrl or tool name → 404; server crash or bad gateway → 5xx; request body rejected → 400.

Common situations: Stale authToken after server restart or key rotation; serverUrl typo or missing /mcp path prefix; MCP server not running or redeployed with a changed tool name; reverse proxy returning 502 while the server is down.

Related errors

AI-assisted analysis of gildas-lormeau/SingleFile@517fb7c5cf (2026-09-01). Data as JSON: /api/errors/73cc4970bdaf4b92. Report an issue: GitHub.