fix: improve 404 error handling to show all relevant parameters (#372)

Instead of trying to guess which resource caused a 404, now we list all
path parameters that were used in the API call. This provides clearer
error messages that help users identify which parameter might be
incorrect.

Example error message:
```
Resource not found. Please verify these parameters are correct:
  - organizationSlug: 'my-org'
  - issueId: 'PROJ-123'
```

Changes:
- Simplified error handling to remove operation tracking
- Tools now only pass path parameters that could cause 404s
- Error messages list all relevant parameters for better debugging

Fixes MCP-SERVER-EA1, MCP-SERVER-E9B

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-authored-by: Claude <[email protected]>

Author: dcramer

packages/mcp-server/src/api-client/client.ts

@@ -264,6 +264,7 @@ export class SentryApiService {
       throw new Error(friendlyMessage, { cause: error });
     }
 
+    // Handle error responses generically
     if (!response.ok) {
       const errorText = await response.text();
       let parsed: unknown | undefined;

packages/mcp-server/src/tools/find-errors.ts

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { setTag } from "@sentry/core";
 import { defineTool } from "./utils/defineTool";
-import { apiServiceFromContext } from "./utils/api-utils";
+import { apiServiceFromContext, withApiErrorHandling } from "./utils/api-utils";
 import type { ServerContext } from "../types";
 import {
   ParamOrganizationSlug,
@@ -73,14 +73,21 @@ export default defineTool({
     setTag("organization.slug", organizationSlug);
     if (params.projectSlug) setTag("project.slug", params.projectSlug);
 
-    const eventList = await apiService.searchErrors({
-      organizationSlug,
-      projectSlug: params.projectSlug,
-      filename: params.filename,
-      query: params.query,
-      transaction: params.transaction,
-      sortBy: params.sortBy as "last_seen" | "count" | undefined,
-    });
+    const eventList = await withApiErrorHandling(
+      () =>
+        apiService.searchErrors({
+          organizationSlug,
+          projectSlug: params.projectSlug,
+          filename: params.filename,
+          query: params.query,
+          transaction: params.transaction,
+          sortBy: params.sortBy as "last_seen" | "count" | undefined,
+        }),
+      {
+        organizationSlug,
+        projectSlug: params.projectSlug,
+      },
+    );
     let output = `# Errors in **${organizationSlug}${params.projectSlug ? `/${params.projectSlug}` : ""}**\n\n`;
     if (params.query)
       output += `These errors match the query \`${params.query}\`\n`;

packages/mcp-server/src/tools/find-issues.ts

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { setTag } from "@sentry/core";
 import { defineTool } from "./utils/defineTool";
-import { apiServiceFromContext } from "./utils/api-utils";
+import { apiServiceFromContext, withApiErrorHandling } from "./utils/api-utils";
 import { UserInputError } from "../errors";
 import type { ServerContext } from "../types";
 import {
@@ -73,14 +73,21 @@ export default defineTool({
       count: "freq" as const,
       userCount: "user" as const,
     };
-    const issues = await apiService.listIssues({
-      organizationSlug,
-      projectSlug: params.projectSlug,
-      query: params.query,
-      sortBy: params.sortBy
-        ? sortByMap[params.sortBy as keyof typeof sortByMap]
-        : undefined,
-    });
+    const issues = await withApiErrorHandling(
+      () =>
+        apiService.listIssues({
+          organizationSlug,
+          projectSlug: params.projectSlug,
+          query: params.query,
+          sortBy: params.sortBy
+            ? sortByMap[params.sortBy as keyof typeof sortByMap]
+            : undefined,
+        }),
+      {
+        organizationSlug,
+        projectSlug: params.projectSlug,
+      },
+    );
     let output = `# Issues in **${organizationSlug}${params.projectSlug ? `/${params.projectSlug}` : ""}**\n\n`;
     if (issues.length === 0) {
       output += "No issues found.\n";

packages/mcp-server/src/tools/find-organizations.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { defineTool } from "./utils/defineTool";
-import { apiServiceFromContext } from "./utils/api-utils";
+import { apiServiceFromContext, withApiErrorHandling } from "./utils/api-utils";
 import type { ServerContext } from "../types";
 
 export default defineTool({
@@ -17,7 +17,10 @@ export default defineTool({
     // User data endpoints (like /users/me/regions/) should never use regionUrl
     // as they must always query the main API server, not region-specific servers
     const apiService = apiServiceFromContext(context);
-    const organizations = await apiService.listOrganizations();
+    const organizations = await withApiErrorHandling(
+      () => apiService.listOrganizations(),
+      {}, // No params for this endpoint
+    );
 
     let output = "# Organizations\n\n";
 

packages/mcp-server/src/tools/get-issue-details.ts

@@ -130,7 +130,10 @@ export default defineTool({
           organizationSlug: orgSlug,
           issueId: parsedIssueId!,
         }),
-      { operation: "getIssue", resourceId: parsedIssueId },
+      {
+        organizationSlug: orgSlug,
+        issueId: parsedIssueId,
+      },
     );
 
     const event = await apiService.getLatestEventForIssue({

packages/mcp-server/src/tools/update-issue.ts

@@ -109,7 +109,10 @@ export default defineTool({
           organizationSlug: orgSlug,
           issueId: parsedIssueId!,
         }),
-      { operation: "getIssue", resourceId: parsedIssueId },
+      {
+        organizationSlug: orgSlug,
+        issueId: parsedIssueId,
+      },
     );
 
     // Update the issue
@@ -121,7 +124,10 @@ export default defineTool({
           status: params.status,
           assignedTo: params.assignedTo,
         }),
-      { operation: "updateIssue", resourceId: parsedIssueId },
+      {
+        organizationSlug: orgSlug,
+        issueId: parsedIssueId,
+      },
     );
 
     let output = `# Issue ${updatedIssue.shortId} Updated in **${orgSlug}**\n\n`;

packages/mcp-server/src/tools/utils/api-utils.test.ts

@@ -4,78 +4,81 @@ import { UserInputError } from "../../errors";
 import { handleApiError, withApiErrorHandling } from "./api-utils";
 
 describe("handleApiError", () => {
-  it("converts 404 errors for issues to UserInputError", () => {
+  it("converts 404 errors with params to list all parameters", () => {
     const error = new ApiError("Not Found", 404);
 
     expect(() =>
-      handleApiError(error, { operation: "getIssue", resourceId: "PROJ-123" }),
+      handleApiError(error, {
+        organizationSlug: "my-org",
+        issueId: "PROJ-123",
+      }),
     ).toThrow(UserInputError);
 
     expect(() =>
-      handleApiError(error, { operation: "getIssue", resourceId: "PROJ-123" }),
+      handleApiError(error, {
+        organizationSlug: "my-org",
+        issueId: "PROJ-123",
+      }),
     ).toThrow(
-      "Issue 'PROJ-123' not found. Please verify the issue ID is correct.",
+      "Resource not found. Please verify these parameters are correct:\n  - organizationSlug: 'my-org'\n  - issueId: 'PROJ-123'",
     );
   });
 
-  it("converts 404 errors for other resources appropriately", () => {
+  it("converts 404 errors with multiple params including nullish values", () => {
     const error = new ApiError("Not Found", 404);
 
     expect(() =>
       handleApiError(error, {
-        operation: "getOrganization",
-        resourceId: "my-org",
+        organizationSlug: "my-org",
+        projectSlug: "my-project",
+        query: undefined,
+        sortBy: null,
+        limit: 0,
+        emptyString: "",
       }),
     ).toThrow(
-      "Organization 'my-org' not found. Please verify the organization slug is correct.",
+      "Resource not found. Please verify these parameters are correct:\n  - organizationSlug: 'my-org'\n  - projectSlug: 'my-project'\n  - limit: '0'",
     );
+  });
 
-    expect(() =>
-      handleApiError(error, {
-        operation: "getProject",
-        resourceId: "my-project",
-      }),
-    ).toThrow(
-      "Project 'my-project' not found. Please verify the project slug is correct.",
+  it("converts 404 errors with no params to generic message", () => {
+    const error = new ApiError("Not Found", 404);
+
+    expect(() => handleApiError(error, {})).toThrow(
+      "Resource not found (404). Please verify that all provided identifiers are correct and you have access to the requested resources.",
     );
   });
 
   it("converts 400 errors to UserInputError", () => {
     const error = new ApiError("Invalid parameters", 400);
 
-    expect(() =>
-      handleApiError(error, { operation: "getIssue", resourceId: "PROJ-123" }),
-    ).toThrow(UserInputError);
+    expect(() => handleApiError(error)).toThrow(UserInputError);
 
-    expect(() =>
-      handleApiError(error, { operation: "getIssue", resourceId: "PROJ-123" }),
-    ).toThrow("Invalid request: Invalid parameters");
+    expect(() => handleApiError(error)).toThrow(
+      "Invalid request: Invalid parameters",
+    );
   });
 
   it("converts 403 errors to UserInputError with access message", () => {
     const error = new ApiError("Forbidden", 403);
 
-    expect(() =>
-      handleApiError(error, { operation: "getIssue", resourceId: "PROJ-123" }),
-    ).toThrow(
+    expect(() => handleApiError(error)).toThrow(
       "Access denied: Forbidden. Please verify you have access to this resource.",
     );
   });
 
   it("re-throws non-API errors unchanged", () => {
     const error = new Error("Network error");
 
-    expect(() =>
-      handleApiError(error, { operation: "getIssue", resourceId: "PROJ-123" }),
-    ).toThrow(error);
+    expect(() => handleApiError(error)).toThrow(error);
   });
 });
 
 describe("withApiErrorHandling", () => {
   it("returns successful results unchanged", async () => {
     const result = await withApiErrorHandling(
       async () => ({ id: "123", title: "Test Issue" }),
-      { operation: "getIssue", resourceId: "PROJ-123" },
+      { issueId: "PROJ-123" },
     );
 
     expect(result).toEqual({ id: "123", title: "Test Issue" });
@@ -89,10 +92,13 @@ describe("withApiErrorHandling", () => {
         async () => {
           throw error;
         },
-        { operation: "getIssue", resourceId: "PROJ-123" },
+        {
+          organizationSlug: "my-org",
+          issueId: "PROJ-123",
+        },
       ),
     ).rejects.toThrow(
-      "Issue 'PROJ-123' not found. Please verify the issue ID is correct.",
+      "Resource not found. Please verify these parameters are correct:\n  - organizationSlug: 'my-org'\n  - issueId: 'PROJ-123'",
     );
   });
 });

packages/mcp-server/src/tools/utils/api-utils.ts

@@ -53,58 +53,36 @@ export function apiServiceFromContext(
 /**
  * Maps API errors to user-friendly errors based on context
  * @param error - The error to handle
- * @param context - Context about what was being attempted
+ * @param params - The parameters that were used in the API call
  * @returns Never - always throws an error
  * @throws {UserInputError} For errors that are clearly user input issues
  * @throws {Error} For other errors
  */
 export function handleApiError(
   error: unknown,
-  context: {
-    operation:
-      | "getIssue"
-      | "updateIssue"
-      | "getEvent"
-      | "getOrganization"
-      | "getProject"
-      | "getTeam";
-    resourceId?: string;
-    resourceType?: string;
-  },
+  params?: Record<string, unknown>,
 ): never {
   if (error instanceof ApiError && error.status === 404) {
-    const resourceType =
-      context.resourceType ||
-      context.operation.replace(/^get|update/, "").toLowerCase();
-    const resourceId = context.resourceId || "unknown";
+    // Build a list of all provided parameters
+    const paramsList: string[] = [];
+    if (params) {
+      for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined && value !== null && value !== "") {
+          paramsList.push(`${key}: '${value}'`);
+        }
+      }
+    }
 
-    switch (context.operation) {
-      case "getIssue":
-      case "updateIssue":
-        throw new UserInputError(
-          `Issue '${resourceId}' not found. Please verify the issue ID is correct.`,
-        );
-      case "getEvent":
-        throw new UserInputError(
-          `Event '${resourceId}' not found. Please verify the event ID is correct.`,
-        );
-      case "getOrganization":
-        throw new UserInputError(
-          `Organization '${resourceId}' not found. Please verify the organization slug is correct.`,
-        );
-      case "getProject":
-        throw new UserInputError(
-          `Project '${resourceId}' not found. Please verify the project slug is correct.`,
-        );
-      case "getTeam":
-        throw new UserInputError(
-          `Team '${resourceId}' not found. Please verify the team slug is correct.`,
-        );
-      default:
-        throw new UserInputError(
-          `${resourceType} '${resourceId}' not found. Please verify the ID is correct.`,
-        );
+    if (paramsList.length > 0) {
+      throw new UserInputError(
+        `Resource not found. Please verify these parameters are correct:\n${paramsList.map((p) => `  - ${p}`).join("\n")}`,
+      );
     }
+
+    // Fallback to generic message if no params provided
+    throw new UserInputError(
+      `Resource not found (404). Please verify that all provided identifiers are correct and you have access to the requested resources.`,
+    );
   }
 
   // For other API errors, check if they're likely user input issues
@@ -129,18 +107,18 @@ export function handleApiError(
 /**
  * Wraps an async API call with automatic error handling
  * @param fn - The async function to execute
- * @param context - Context about what operation is being performed
+ * @param params - The parameters that were used in the API call
  * @returns The result of the function
  * @throws {UserInputError} For user input errors
  * @throws {Error} For other errors
  */
 export async function withApiErrorHandling<T>(
   fn: () => Promise<T>,
-  context: Parameters<typeof handleApiError>[1],
+  params?: Record<string, unknown>,
 ): Promise<T> {
   try {
     return await fn();
   } catch (error) {
-    handleApiError(error, context);
+    handleApiError(error, params);
   }
 }