modelcontextprotocol/servers · error · UrlElicitationRequiredError

-32042

-32042

Error message

This request requires browser-based authorization.

What it means

Thrown as `UrlElicitationRequiredError` (MCP error code -32042) by the `trigger-url-elicitation` tool when `errorPath=true` and the call is the originating (non-retry) request. It signals the client that a prerequisite browser-based URL elicitation must be satisfied before the request can proceed. The tool remembers the issued prerequisite; a retry with the same stable key (session+url+callerElicitationId) clears the marker and falls through to the request path.

Source

Thrown at src/everything/tools/trigger-url-elicitation.ts:165

        //     path. Without this, the retry would re-enter the error path and
        //     re-request the prerequisite URL — another loop.
        if (errorPath) {
          if (issuedErrorPathElicitations.has(errorPathKey)) {
            // Retry of a satisfied prerequisite: clear the one-shot marker and
            // ignore errorPath, falling through to the request path below.
            issuedErrorPathElicitations.delete(errorPathKey);
          } else {
            // Originating call: record that we issued a prerequisite for this
            // request, then signal the client via -32042.
            issuedErrorPathElicitations.add(errorPathKey);
            const prerequisiteElicitation: ElicitRequestURLParams = {
              mode: "url",
              url: "https://modelcontextprotocol.io",
              message:
                "Open this link to satisfy the prerequisite, then retry the request.",
              elicitationId: randomUUID(),
            };
            throw new UrlElicitationRequiredError(
              [prerequisiteElicitation],
              "This request requires browser-based authorization."
            );
          }
        }

        // Request path: send elicitation/create and await the user's response
        const elicitationResult = await extra.sendRequest(
          {
            method: "elicitation/create",
            params: elicitationParams,
          },
          ElicitResultSchema,
          { timeout: 10 * 60 * 1000 /* 10 minutes */ }
        );

        // Handle different response actions
        const content: CallToolResult["content"] = [];

View on GitHub (pinned to 76d64c822f)

Solutions

  1. Satisfy the prerequisite URL elicitation, then retry the original call with identical arguments (same url and caller-supplied elicitationId) so the marker matches and errorPath is ignored.
  2. If you don't want the error-path flow, call the tool with `errorPath: false` (default) to use the request path directly.
  3. Ensure the client advertises `elicitation.url` capability in initialize; otherwise the tool is not registered at all.

Example fix

// before: client ignores -32042 and retries with a new elicitationId each time
// after: satisfy the prerequisite, then retry with the SAME url + callerElicitationId
callTool({ url: 'https://app/auth', errorPath: true, elicitationId: 'stable-id' });
// ... satisfy prerequisite ...
callTool({ url: 'https://app/auth', errorPath: true, elicitationId: 'stable-id' }); // falls through
Defensive patterns

Strategy: try-catch

Validate before calling

// choose request path to avoid the error entirely
callTool({ url, message, errorPath: false });
// or, for error path: keep callerElicitationId stable across retries
callTool({ url, message, errorPath: true, elicitationId: 'stable-id' });

Try / catch

try {
  await callTool({ url, errorPath: true, elicitationId: 'stable-id' });
} catch (e) {
  if (e instanceof UrlElicitationRequiredError) {
    // satisfy the prerequisite URL, then RETRY with identical args (same url + elicitationId)
    await satisfyPrerequisite(e.elicitations);
    await callTool({ url, errorPath: true, elicitationId: 'stable-id' });
  }
}

Prevention

When it happens

Trigger: Calling `trigger-url-elicitation` with `{ errorPath: true, url: ... }` for the first time in a session for that url. The thrown error carries a prerequisite elicitation pointing at `https://modelcontextprotocol.io`. Retrying the identical call after satisfying the prerequisite does NOT re-throw.

Common situations: Client does not handle -32042 / URL-elicitation capability, retries with different arguments (changing url or elicitationId) so the one-shot key never matches, or never satisfies the prerequisite so retries keep missing the marker-removal branch. Also: clients that don't advertise `elicitation.url` capability won't even see the tool registered.

Related errors

AI-assisted analysis of modelcontextprotocol/servers@76d64c822f (2026-08-12). Data as JSON: /api/errors/360a64c51770c789. Report an issue: GitHub.