fix(errors): add ResolutionError for not-found/ambiguous resolution failures (#293)

## Summary

- Fixes confusing errors like `Issue 99124558 is required.` (Sentry
issue CLI-8C) — these appeared when a numeric issue ID was looked up but
not found, misusing `ContextError` which is meant for omitted required
values
- Adds a new `ResolutionError` class for when the user *provided* a
value that couldn't be resolved, with a structured format: `${resource}
${headline}.\n\nTry:\n ${hint}\n\nOr:\n - ${suggestions}`
- Migrates 12 callsites across `issue/utils.ts`, `resolve-target.ts`,
`event/view.ts`, and `issue/list.ts` from `ContextError` to
`ResolutionError` with appropriate headlines (`not found`, `is
ambiguous`, `could not be resolved`)

## Before / After

**Before:**
```
Issue 99124558 is required.

Try:
  sentry issue view <org>/99124558
```

**After:**
```
Issue 99124558 not found.

Try:
  sentry issue view <org>/99124558

Or:
  - No issue with numeric ID 99124558 found — you may not have access or it belongs to a different org
  - If this is a short ID suffix, try: sentry issue view <project>-99124558
```

Author: BYK

src/commands/event/view.ts

@@ -19,7 +19,7 @@ import {
 } from "../../lib/arg-parsing.js";
 import { openInBrowser } from "../../lib/browser.js";
 import { buildCommand } from "../../lib/command.js";
-import { ContextError } from "../../lib/errors.js";
+import { ContextError, ResolutionError } from "../../lib/errors.js";
 import { formatEventDetails, writeJson } from "../../lib/formatters/index.js";
 import {
   resolveOrgAndProject,
@@ -221,9 +221,10 @@ export async function resolveOrgAllTarget(
 ): Promise<ResolvedEventTarget> {
   const resolved = await resolveEventInOrg(org, eventId);
   if (!resolved) {
-    throw new ContextError(
+    throw new ResolutionError(
       `Event ${eventId} in organization "${org}"`,
-      `sentry event view ${org}/ ${eventId}`
+      "not found",
+      `sentry event view ${org}/<project> ${eventId}`
     );
   }
   return {

src/commands/issue/list.ts

@@ -31,6 +31,7 @@ import {
   ApiError,
   AuthError,
   ContextError,
+  ResolutionError,
   ValidationError,
 } from "../../lib/errors.js";
 import {
@@ -352,10 +353,11 @@ async function resolveTargetsFromParsedArg(
       const matches = await findProjectsBySlug(parsed.projectSlug);
 
       if (matches.length === 0) {
-        throw new ContextError(
-          "Project",
-          `No project '${parsed.projectSlug}' found in any accessible organization.\n\n` +
-            `Try: sentry issue list <org>/${parsed.projectSlug}`
+        throw new ResolutionError(
+          `Project '${parsed.projectSlug}'`,
+          "not found",
+          `sentry issue list <org>/${parsed.projectSlug}`,
+          ["No project with this slug found in any accessible organization"]
         );
       }
 

src/commands/issue/utils.ts

@@ -14,7 +14,7 @@ import {
 import { parseIssueArg } from "../../lib/arg-parsing.js";
 import { getProjectByAlias } from "../../lib/db/project-aliases.js";
 import { detectAllDsns } from "../../lib/dsn/index.js";
-import { ApiError, ContextError } from "../../lib/errors.js";
+import { ApiError, ContextError, ResolutionError } from "../../lib/errors.js";
 import { getProgressMessage } from "../../lib/formatters/seer.js";
 import { expandToFullShortId, isShortSuffix } from "../../lib/issue-id.js";
 import { poll } from "../../lib/polling.js";
@@ -140,15 +140,19 @@ async function resolveProjectSearch(
   const projects = await findProjectsBySlug(projectSlug.toLowerCase());
 
   if (projects.length === 0) {
-    throw new ContextError(`Project '${projectSlug}' not found`, commandHint, [
-      "No project with this slug found in any accessible organization",
-    ]);
+    throw new ResolutionError(
+      `Project '${projectSlug}'`,
+      "not found",
+      commandHint,
+      ["No project with this slug found in any accessible organization"]
+    );
   }
 
   if (projects.length > 1) {
     const orgList = projects.map((p) => p.orgSlug).join(", ");
-    throw new ContextError(
-      `Project '${projectSlug}' found in multiple organizations`,
+    throw new ResolutionError(
+      `Project '${projectSlug}'`,
+      "is ambiguous",
       commandHint,
       [
         `Found in: ${orgList}`,
@@ -159,7 +163,11 @@ async function resolveProjectSearch(
 
   const project = projects[0];
   if (!project) {
-    throw new ContextError(`Project '${projectSlug}' not found`, commandHint);
+    throw new ResolutionError(
+      `Project '${projectSlug}'`,
+      "not found",
+      commandHint
+    );
   }
 
   const fullShortId = expandToFullShortId(suffix, project.slug);
@@ -181,8 +189,9 @@ async function resolveSuffixOnly(
 ): Promise<StrictResolvedIssue> {
   const target = await resolveOrgAndProject({ cwd });
   if (!target) {
-    throw new ContextError(
-      `Cannot resolve issue suffix '${suffix}' without project context`,
+    throw new ResolutionError(
+      `Issue suffix '${suffix}'`,
+      "could not be resolved without project context",
       commandHint
     );
   }
@@ -208,8 +217,9 @@ function resolveExplicitOrgSuffix(
   suffix: string,
   commandHint: string
 ): never {
-  throw new ContextError(
-    `Cannot resolve suffix '${suffix}' without project context`,
+  throw new ResolutionError(
+    `Issue suffix '${suffix}'`,
+    "could not be resolved without project context",
     commandHint,
     [
       `The format '${org}/${suffix}' requires a project to build the full issue ID.`,
@@ -243,7 +253,8 @@ export type ResolveIssueOptions = {
  *
  * @param options - Resolution options
  * @returns Object with org slug and full issue
- * @throws {ContextError} When required context cannot be resolved
+ * @throws {ContextError} When required context (org) is missing
+ * @throws {ResolutionError} When an issue or project could not be found or resolved
  */
 export async function resolveIssue(
   options: ResolveIssueOptions
@@ -263,10 +274,15 @@ export async function resolveIssue(
           // Improve on the generic "Issue not found" message by including the ID
           // and suggesting the short-ID format, since users often confuse numeric
           // group IDs with short-ID suffixes.
-          throw new ContextError(`Issue ${parsed.id}`, commandHint, [
-            `No issue with numeric ID ${parsed.id} found — you may not have access, or it may have been deleted.`,
-            `If this is a short ID suffix, try: sentry issue ${command} <project>-${parsed.id}`,
-          ]);
+          throw new ResolutionError(
+            `Issue ${parsed.id}`,
+            "not found",
+            commandHint,
+            [
+              `No issue with numeric ID ${parsed.id} found — you may not have access, or it may have been deleted.`,
+              `If this is a short ID suffix, try: sentry issue ${command} <project>-${parsed.id}`,
+            ]
+          );
         }
         throw err;
       }
@@ -286,10 +302,15 @@ export async function resolveIssue(
         return { org: parsed.org, issue };
       } catch (err) {
         if (err instanceof ApiError && err.status === 404) {
-          throw new ContextError(`Issue ${parsed.numericId}`, commandHint, [
-            `No issue with numeric ID ${parsed.numericId} found in org '${parsed.org}' — you may not have access, or it may have been deleted.`,
-            `If this is a short ID suffix, try: sentry issue ${command} <project>-${parsed.numericId}`,
-          ]);
+          throw new ResolutionError(
+            `Issue ${parsed.numericId}`,
+            "not found",
+            commandHint,
+            [
+              `No issue with numeric ID ${parsed.numericId} found in org '${parsed.org}' — you may not have access, or it may have been deleted.`,
+              `If this is a short ID suffix, try: sentry issue ${command} <project>-${parsed.numericId}`,
+            ]
+          );
         }
         throw err;
       }

src/lib/errors.ts

@@ -163,6 +163,31 @@ function buildContextMessage(
   return lines.join("\n");
 }
 
+/**
+ * Build the formatted resolution error message for entities that could not be found or resolved.
+ *
+ * @param resource - The entity that could not be resolved (e.g., "Issue 99124558")
+ * @param headline - Describes the failure (e.g., "not found", "is ambiguous", "could not be resolved")
+ * @param hint - Primary usage example or suggestion
+ * @param suggestions - Additional help bullets shown under "Or:"
+ * @returns Formatted multi-line error message
+ */
+function buildResolutionMessage(
+  resource: string,
+  headline: string,
+  hint: string,
+  suggestions: string[]
+): string {
+  const lines = [`${resource} ${headline}.`, "", "Try:", `  ${hint}`];
+  if (suggestions.length > 0) {
+    lines.push("", "Or:");
+    for (const s of suggestions) {
+      lines.push(`  - ${s}`);
+    }
+  }
+  return lines.join("\n");
+}
+
 /**
  * Missing required context errors (org, project, etc).
  *
@@ -196,6 +221,43 @@ export class ContextError extends CliError {
   }
 }
 
+/**
+ * Resolution errors for entities that exist but could not be found or resolved.
+ *
+ * Use this when the user provided a value but it could not be matched — as
+ * opposed to {@link ContextError}, which is for when the user omitted a
+ * required value entirely.
+ *
+ * @param resource - The entity that failed to resolve (e.g., "Issue 99124558", "Project 'cli'")
+ * @param headline - Short phrase describing the failure (e.g., "not found", "is ambiguous", "could not be resolved")
+ * @param hint - Primary usage example or suggestion (shown under "Try:")
+ * @param suggestions - Additional help bullets shown under "Or:" (defaults to empty)
+ */
+export class ResolutionError extends CliError {
+  readonly resource: string;
+  readonly headline: string;
+  readonly hint: string;
+  readonly suggestions: string[];
+
+  constructor(
+    resource: string,
+    headline: string,
+    hint: string,
+    suggestions: string[] = []
+  ) {
+    super(buildResolutionMessage(resource, headline, hint, suggestions));
+    this.name = "ResolutionError";
+    this.resource = resource;
+    this.headline = headline;
+    this.hint = hint;
+    this.suggestions = suggestions;
+  }
+
+  override format(): string {
+    return this.message;
+  }
+}
+
 /**
  * Input validation errors.
  *

src/lib/resolve-target.ts

@@ -37,7 +37,12 @@ import {
   formatMultipleProjectsFooter,
   getDsnSourceDescription,
 } from "./dsn/index.js";
-import { AuthError, ContextError, ValidationError } from "./errors.js";
+import {
+  AuthError,
+  ContextError,
+  ResolutionError,
+  ValidationError,
+} from "./errors.js";
 import { warning } from "./formatters/colors.js";
 import { isAllDigits } from "./utils.js";
 
@@ -793,11 +798,16 @@ export async function resolveProjectBySlug(
 ): Promise<{ org: string; project: string }> {
   const found = await findProjectsBySlug(projectSlug);
   if (found.length === 0) {
-    throw new ContextError(`Project "${projectSlug}"`, usageHint, [
-      isAllDigits(projectSlug)
-        ? "No project with this ID was found — check the ID or use the project slug instead"
-        : "Check that you have access to a project with this slug",
-    ]);
+    throw new ResolutionError(
+      `Project "${projectSlug}"`,
+      "not found",
+      usageHint,
+      [
+        isAllDigits(projectSlug)
+          ? "No project with this ID was found — check the ID or use the project slug instead"
+          : "Check that you have access to a project with this slug",
+      ]
+    );
   }
   if (found.length > 1) {
     const orgList = found.map((p) => `  ${p.orgSlug}/${p.slug}`).join("\n");
@@ -935,20 +945,23 @@ export async function resolveOrgProjectTarget(
       const matches = await findProjectsBySlug(parsed.projectSlug);
 
       if (matches.length === 0) {
-        throw new ContextError(
-          "Project",
-          `No project '${parsed.projectSlug}' found in any accessible organization.\n\n` +
-            `Try: sentry ${commandName} <org>/${parsed.projectSlug}`
+        throw new ResolutionError(
+          `Project '${parsed.projectSlug}'`,
+          "not found",
+          `sentry ${commandName} <org>/${parsed.projectSlug}`,
+          ["No project with this slug found in any accessible organization"]
         );
       }
 
       if (matches.length > 1) {
         const options = matches
           .map((m) => `  sentry ${commandName} ${m.orgSlug}/${m.slug}`)
           .join("\n");
-        throw new ContextError(
-          "Project",
-          `Found '${parsed.projectSlug}' in ${matches.length} organizations. Please specify:\n${options}`
+        throw new ResolutionError(
+          `Project '${parsed.projectSlug}'`,
+          "is ambiguous",
+          `sentry ${commandName} <org>/${parsed.projectSlug}`,
+          [`Found in ${matches.length} organizations. Specify one:\n${options}`]
         );
       }
 

test/commands/event/view.test.ts

@@ -24,7 +24,11 @@ import type { ProjectWithOrg } from "../../../src/lib/api-client.js";
 // biome-ignore lint/performance/noNamespaceImport: needed for spyOn mocking
 import * as apiClient from "../../../src/lib/api-client.js";
 import { ProjectSpecificationType } from "../../../src/lib/arg-parsing.js";
-import { ContextError, ValidationError } from "../../../src/lib/errors.js";
+import {
+  ContextError,
+  ResolutionError,
+  ValidationError,
+} from "../../../src/lib/errors.js";
 // biome-ignore lint/performance/noNamespaceImport: needed for spyOn mocking
 import * as resolveTarget from "../../../src/lib/resolve-target.js";
 import { resolveProjectBySlug } from "../../../src/lib/resolve-target.js";
@@ -221,11 +225,11 @@ describe("resolveProjectBySlug", () => {
   });
 
   describe("no projects found", () => {
-    test("throws ContextError when project not found", async () => {
+    test("throws ResolutionError when project not found", async () => {
       findProjectsBySlugSpy.mockResolvedValue([]);
 
       await expect(resolveProjectBySlug("my-project", HINT)).rejects.toThrow(
-        ContextError
+        ResolutionError
       );
     });
 
@@ -236,11 +240,15 @@ describe("resolveProjectBySlug", () => {
         await resolveProjectBySlug("frontend", HINT);
         expect.unreachable("Should have thrown");
       } catch (error) {
-        expect(error).toBeInstanceOf(ContextError);
-        expect((error as ContextError).message).toContain('Project "frontend"');
-        expect((error as ContextError).message).toContain(
+        expect(error).toBeInstanceOf(ResolutionError);
+        expect((error as ResolutionError).message).toContain(
+          'Project "frontend"'
+        );
+        expect((error as ResolutionError).message).toContain(
           "Check that you have access"
         );
+        // Message says "not found", not "is required"
+        expect((error as ResolutionError).message).toContain("not found");
       }
     });
   });
@@ -352,10 +360,12 @@ describe("resolveProjectBySlug", () => {
         await resolveProjectBySlug("7275560680", HINT);
         expect.unreachable("Should have thrown");
       } catch (error) {
-        expect(error).toBeInstanceOf(ContextError);
-        const message = (error as ContextError).message;
+        expect(error).toBeInstanceOf(ResolutionError);
+        const message = (error as ResolutionError).message;
         expect(message).toContain('Project "7275560680"');
         expect(message).toContain("No project with this ID was found");
+        // Message says "not found", not "is required"
+        expect(message).toContain("not found");
       }
     });
 
@@ -544,12 +554,12 @@ describe("resolveOrgAllTarget", () => {
     expect(result?.prefetchedEvent?.eventID).toBe("abc123");
   });
 
-  test("throws ContextError when event not found in explicit org", async () => {
+  test("throws ResolutionError when event not found in explicit org", async () => {
     resolveEventInOrgSpy.mockResolvedValue(null);
 
     await expect(
       resolveOrgAllTarget("acme", "notfound", "/tmp")
-    ).rejects.toBeInstanceOf(ContextError);
+    ).rejects.toBeInstanceOf(ResolutionError);
   });
 
   test("propagates errors from resolveEventInOrg", async () => {