chore(cli): re-enable Sentry reporting for unclassified errors (fallback to InternalError) by FedeZara · Pull Request #14752 · fern-api/fern

FedeZara · 2026-04-08T15:38:25Z

Description

Re-enables Sentry reporting for unclassified errors by changing the Unclassified error code to fall back to InternalError for Sentry reporting purposes.

This is part of the error classification system introduced in #14749.

Changes Made

Updated the Sentry routing configuration in CliError.ts so that Unclassified errors are reported to Sentry (treated as InternalError until properly classified).

Error codes used

Code	Change
`Unclassified`	Now reported to Sentry (was previously suppressed during the migration rollout)

Files touched (grouped by area)

CliError: packages/cli/task-context/src/CliError.ts — changed UNCLASSIFIED Sentry reportability from false to true

Testing

Existing tests pass (pnpm test, excluding e2e)

github-actions · 2026-04-08T15:39:20Z

claude

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review to trigger a review and subscribe this PR to future pushes, or @claude review once for a one-time review.

_{Tip: disable this comment in your organization's Code Review settings.}

Swimburger · 2026-04-10T14:11:26Z

        return "ENVIRONMENT_ERROR";
    }
-    return "UNCLASSIFIED";
+    return "INTERNAL_ERROR";


use your code map

graphite-app · 2026-04-10T14:49:27Z

-        this.code = code;
-        this.docsLink = docsLink;
-    }
+export const CliError.Code = {


Invalid syntax: export const CliError.Code = {...} is not valid TypeScript/JavaScript. Dot notation cannot be used in a const declaration outside of a namespace or class.

The original code had this inside a namespace CliError block. This refactor breaks the syntax. The code will fail to compile.

Fix: Either keep the namespace structure or use a different approach:

export namespace CliError { export const Code = { InternalError: "INTERNAL_ERROR", // ... rest of codes } as const; export type Code = (typeof Code)[keyof typeof Code]; }

Suggested change

export const CliError.Code = {

export namespace CliError {

export const Code = {

Spotted by Graphite

Is this helpful? React 👍 or 👎 to let us know.

FedeZara · 2026-04-10T17:09:46Z

This stack of pull requests is managed by Graphite. Learn more about stacking.

…entry routing (#14749) ## Description Introduces a structured `CliError` class in `@fern-api/task-context` with typed error codes and automatic Sentry routing. This replaces the ad-hoc `new Error(...)` pattern throughout the CLI with a system that categorizes errors into user-facing codes (e.g. `CONFIG_ERROR`, `AUTH_ERROR`) vs internal errors that should be reported to Sentry. It also simplifies error handling by removing redundant error classes and unifying the ones we already have. > **Recommended review approach:** commit-by-commit. Each commit is self-contained and builds on the previous one. ### Prerequisite PRs - #14746 — rename `FernCliError` to `TaskAbortSignal` (clears the naming space) - #14747 — make CLI v1 telemetry synchronous (so `failWithoutThrowing` can report errors) - #14748 — make CLI v2 telemetry synchronous (same, for CLI v2) ### Follow-up PRs - #14750 — temporarily disable Sentry for unclassified errors (safety net while migrating) - #14753 — migrate `@fern-api/cli` package (example of a package migration PR) - ~34 more package migration PRs (one per package, converting `new Error(...)` → `new CliError(...)` and adding error codes to `failAndThrow` and `failWithoutThrowing` calls) - #14752 — re-enable Sentry for unclassified errors (merge last, after all migrations) ## Design Decisions ### Two ways to trigger and track errors There are two paths through which errors are captured and reported: 1. **Throwing `CliError` directly.** Code anywhere in the CLI can `throw new CliError({ message, code })`. The top-level catch handler in each CLI entry point (CLI v1's `runCli` catch in `cli.ts`, CLI v2's `withContext` catch in `withContext.ts`) intercepts it, resolves the error code, and routes it to Sentry and/or PostHog. 2. **Calling `failAndThrow` / `failWithoutThrowing` on the task context.** These methods log the error, resolve the code (explicit override > `CliError.code` > fallback), and report to Sentry if the code is Sentry-reportable. `failAndThrow` then throws a `TaskAbortSignal` to unwind the stack; `failWithoutThrowing` marks the task as failed and returns. This is the preferred path when the caller needs control over what happens after the error — for example, to continue processing other tasks or to clean up resources before aborting. It also adapts naturally to the existing error-handling patterns already used throughout the codebase. Both paths converge on the same code-resolution logic (`resolveErrorCode`) and Sentry-routing rules (`shouldReportToSentry`), so tracking is consistent regardless of which path is used. ### Default behavior: unclassified errors are internal Any error that doesn't carry a `CliError.Code` (i.e. a plain `new Error(...)`) is treated as `INTERNAL_ERROR` at the top-level catch boundaries — and therefore reported to Sentry. The assumption is that if nobody explicitly categorized an error as user-facing, it's likely an internal bug. **Temporary exception:** the follow-up PR #14750 temporarily downgrades this so unclassified errors skip Sentry during the migration period, to avoid noise from the ~34 packages that haven't been migrated yet. Once all migrations land, #14752 re-enables it. ### Error code taxonomy Errors are classified into 12 typed codes: | Code | Sentry? | Description | |------|---------|-------------| | `INTERNAL_ERROR` | Yes | Unexpected bugs — should be investigated | | `RESOLUTION_ERROR` | Yes | Type/reference resolution failures (likely IR bugs) | | `IR_CONVERSION_ERROR` | Yes | IR generation failures | | `CONTAINER_ERROR` | Yes | Docker container failures | | `VERSION_ERROR` | Yes | Version parsing/compatibility issues | | `PARSE_ERROR` | No | Malformed user input (YAML, OpenAPI, etc.) | | `ENVIRONMENT_ERROR` | No | Missing env vars, wrong Node version, etc. | | `REFERENCE_ERROR` | No | Dangling references in user config | | `VALIDATION_ERROR` | No | Schema/rule validation failures | | `NETWORK_ERROR` | No | HTTP failures, timeouts | | `AUTH_ERROR` | No | Authentication/authorization issues | | `CONFIG_ERROR` | No | Invalid generators.yml, fern.config.json, etc. | Only the first 5 codes are Sentry-reportable — they indicate bugs in Fern itself. The rest are user-actionable and would just create noise in Sentry. ### Simplifying error handling by removing redundant classes - **Unified `CliError` across CLI v1 and v2.** CLI v2 had its own `CliError` class in `packages/cli/cli-v2/src/errors/CliError.ts`. This PR deletes it and makes both CLIs share the single `CliError` from `@fern-api/task-context`, ensuring consistent error codes and Sentry routing regardless of which CLI entry point is used. - **Existing error classes now extend `CliError`.** `ValidationError`, `SourcedValidationError`, and `KeyringUnavailableError` now extend `CliError` with their appropriate codes (`VALIDATION_ERROR` and `AUTH_ERROR`). This means `resolveErrorCode()` handles them automatically — no special-casing needed in every catch block. - **Removed `LoggableFernCliError`.** This was a wrapper that carried a log message alongside an error. With `CliError` now carrying a `message` field (it extends `Error`), the wrapper is redundant. All former `LoggableFernCliError` usages are replaced with `CliError`. ### `reportError` — single error reporting path (CLI v2) CLI v2's `withContext.ts` previously had separate `shouldReportToSentry` and `extractErrorCode` functions. These are consolidated into a single `reportError(context, error, options?)` function that: 1. Skips `TaskAbortSignal` (already logged) 2. Resolves the error code via `resolveErrorCode()` (explicit override > `CliError.code` > fallback to `INTERNAL_ERROR`) 3. Reports to Sentry if the code is in `SENTRY_REPORTABLE_CODES` 4. Always reports to PostHog with the error code as a property ### Sentry tags Error codes are now passed as Sentry tags (`errorCode`) on captured exceptions, making it possible to filter and alert on specific error categories in the Sentry dashboard. ## Commits (review in order) 1. **`add shared CliError class`** — introduces `CliError` in `@fern-api/task-context` with the code taxonomy, `shouldReportToSentry`, `resolveErrorCode`, and static factory methods 2. **`unify CLI v2 CliError`** — deletes CLI v2's local `CliError`, switches to shared one, introduces `reportError` in `withContext.ts` 3. **`clean up imports`** — mechanical import reordering for consistency 4. **`make error classes extend CliError`** — `ValidationError`, `SourcedValidationError`, `KeyringUnavailableError` now extend `CliError` 5. **`pass error code as Sentry tag`** — adds `errorCode` tag to `captureException` calls 6. **`remove LoggableFernCliError`** — replaces all usages with `CliError`, deletes the class ## Testing - [x] Updated test helpers and mocks for new `CliError` / `MockTaskContext` signatures - [x] Existing CLI v1 and v2 tests pass  --- <a href="https://app.devin.ai/review/fern-api/fern/pull/14749" target="_blank"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://static.devin.ai/assets/gh-open-in-devin-review-dark.svg?v=1"> <img src="https://static.devin.ai/assets/gh-open-in-devin-review-light.svg?v=1" alt="Open with Devin"> </picture> </a>

…ors (#14750) ## Description Part of the CLI error classification effort — see #14749 for full context. Temporarily suppresses Sentry reporting for errors that haven't been classified yet. This is a safety net so that merging #14749 doesn't flood Sentry with noise while the ~35 follow-up package migration PRs are landing. ## Changes Made - Added `UNCLASSIFIED` to `CliError.Code` - Default error code fallback changed from `INTERNAL_ERROR` to `UNCLASSIFIED` in: - `cli.ts` (CLI v1 top-level catch) - `CliContext.ts` (CLI v1 task runner) - `withContext.ts` → `reportError` (CLI v2) - `UNCLASSIFIED` is **not** in `SENTRY_REPORTABLE_CODES`, so these errors are silently tracked in PostHog but not sent to Sentry ## Rollback Once all package migration PRs have landed, #14752 will remove `UNCLASSIFIED` and revert the fallback to `INTERNAL_ERROR`. ## Testing - [x] Existing tests pass (only changes default string literals)

…ack to InternalError)

FedeZara self-assigned this Apr 8, 2026

claude bot reviewed Apr 8, 2026

View reviewed changes

This was referenced Apr 8, 2026

feat(cli): introduce structured CliError with typed error codes and Sentry routing #14749

Merged

chore(cli): temporarily disable Sentry reporting for unclassified errors #14750

Merged

FedeZara force-pushed the FedeZara/refactor/cli-error-disable-uncategorized-sentry branch 2 times, most recently from fd89650 to 6e6d684 Compare April 9, 2026 22:38

FedeZara force-pushed the FedeZara/refactor/cli-error-reenable-sentry branch 2 times, most recently from 6172072 to ea44cc1 Compare April 9, 2026 23:14

FedeZara force-pushed the FedeZara/refactor/cli-error-disable-uncategorized-sentry branch 2 times, most recently from ab973cc to fd585dd Compare April 10, 2026 12:18

FedeZara force-pushed the FedeZara/refactor/cli-error-reenable-sentry branch from ea44cc1 to a1d4044 Compare April 10, 2026 12:18

Swimburger approved these changes Apr 10, 2026

View reviewed changes

FedeZara force-pushed the FedeZara/refactor/cli-error-disable-uncategorized-sentry branch from fd585dd to 630e15e Compare April 10, 2026 14:44

FedeZara force-pushed the FedeZara/refactor/cli-error-reenable-sentry branch from a1d4044 to 4221daf Compare April 10, 2026 14:45

graphite-app bot reviewed Apr 10, 2026

View reviewed changes

FedeZara force-pushed the FedeZara/refactor/cli-error-reenable-sentry branch from 4221daf to 9ddd177 Compare April 10, 2026 15:07

FedeZara force-pushed the FedeZara/refactor/cli-error-disable-uncategorized-sentry branch 2 times, most recently from 68c2b60 to 0549359 Compare April 10, 2026 16:20

FedeZara force-pushed the FedeZara/refactor/cli-error-reenable-sentry branch from 9ddd177 to de49afc Compare April 10, 2026 17:09

FedeZara force-pushed the FedeZara/refactor/cli-error-disable-uncategorized-sentry branch from 0549359 to 813f087 Compare April 10, 2026 17:09

This was referenced Apr 10, 2026

chore(cli): rename FernCliError to TaskAbortSignal #14746

Merged

chore(cli): make instrumentPostHogEvent synchronous #14747

Merged

chore(cli): eagerly resolve TelemetryClient distinctId via async factory #14748

Merged

FedeZara mentioned this pull request Apr 10, 2026

chore(cli): migrate @fern-api/cli to use CliError #14753

Merged

1 task

FedeZara force-pushed the FedeZara/refactor/cli-error-disable-uncategorized-sentry branch from 813f087 to 21e744b Compare April 10, 2026 17:43

FedeZara force-pushed the FedeZara/refactor/cli-error-reenable-sentry branch from de49afc to 0bd6ba6 Compare April 10, 2026 17:43

FedeZara force-pushed the FedeZara/refactor/cli-error-disable-uncategorized-sentry branch from 21e744b to b9b9c99 Compare April 10, 2026 18:33

FedeZara force-pushed the FedeZara/refactor/cli-error-reenable-sentry branch from 0bd6ba6 to a6379df Compare April 10, 2026 18:33

FedeZara force-pushed the FedeZara/refactor/cli-error-reenable-sentry branch from a6379df to d2a8aa2 Compare April 10, 2026 18:42

FedeZara force-pushed the FedeZara/refactor/cli-error-disable-uncategorized-sentry branch from b9b9c99 to a67cf84 Compare April 10, 2026 18:42

FedeZara force-pushed the FedeZara/refactor/cli-error-reenable-sentry branch from d2a8aa2 to 3c229d7 Compare April 10, 2026 18:58

FedeZara force-pushed the FedeZara/refactor/cli-error-disable-uncategorized-sentry branch 2 times, most recently from 0b71fc4 to dc33e43 Compare April 10, 2026 19:42

FedeZara force-pushed the FedeZara/refactor/cli-error-reenable-sentry branch from 3c229d7 to 0ffbee0 Compare April 10, 2026 19:42

FedeZara force-pushed the FedeZara/refactor/cli-error-disable-uncategorized-sentry branch from dc33e43 to 7a7c757 Compare April 10, 2026 21:55

FedeZara force-pushed the FedeZara/refactor/cli-error-reenable-sentry branch from 0ffbee0 to 6933edf Compare April 10, 2026 21:55

FedeZara force-pushed the FedeZara/refactor/cli-error-disable-uncategorized-sentry branch from 7a7c757 to f473624 Compare April 10, 2026 22:16

FedeZara force-pushed the FedeZara/refactor/cli-error-reenable-sentry branch from 6933edf to a5478b0 Compare April 10, 2026 22:16

FedeZara force-pushed the FedeZara/refactor/cli-error-disable-uncategorized-sentry branch from f473624 to 41d0da0 Compare April 10, 2026 22:24

FedeZara force-pushed the FedeZara/refactor/cli-error-reenable-sentry branch 2 times, most recently from 6a1d5d5 to dbdaa7e Compare April 14, 2026 18:22

FedeZara force-pushed the FedeZara/refactor/cli-error-disable-uncategorized-sentry branch from 41d0da0 to f45d891 Compare April 14, 2026 18:22

FedeZara force-pushed the FedeZara/refactor/cli-error-disable-uncategorized-sentry branch 2 times, most recently from b49bf53 to a00c1d7 Compare April 14, 2026 18:43

FedeZara force-pushed the FedeZara/refactor/cli-error-reenable-sentry branch from dbdaa7e to 8c63a12 Compare April 14, 2026 18:43

FedeZara changed the base branch from FedeZara/refactor/cli-error-disable-uncategorized-sentry to graphite-base/14752 April 14, 2026 18:51

FedeZara force-pushed the FedeZara/refactor/cli-error-reenable-sentry branch from 8c63a12 to af973e4 Compare April 14, 2026 18:51

FedeZara force-pushed the graphite-base/14752 branch from a00c1d7 to 063113b Compare April 14, 2026 18:51

graphite-app bot changed the base branch from graphite-base/14752 to main April 14, 2026 18:52

FedeZara force-pushed the FedeZara/refactor/cli-error-reenable-sentry branch 2 times, most recently from e644f5a to 201c490 Compare April 14, 2026 21:28

FedeZara changed the title ~~chore(cli): re-enable Sentry reporting for unclassified errors~~ chore(cli): re-enable Sentry reporting for unclassified errors (fallback to InternalError) Apr 14, 2026

FedeZara force-pushed the FedeZara/refactor/cli-error-reenable-sentry branch from 201c490 to 0cad4b7 Compare April 14, 2026 22:43

chore(cli): re-enable Sentry reporting for unclassified errors (fallb…

67ac32d

…ack to InternalError)

FedeZara force-pushed the FedeZara/refactor/cli-error-reenable-sentry branch from 0cad4b7 to 67ac32d Compare April 15, 2026 12:52

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

chore(cli): re-enable Sentry reporting for unclassified errors (fallback to InternalError)#14752

chore(cli): re-enable Sentry reporting for unclassified errors (fallback to InternalError)#14752
FedeZara wants to merge 1 commit intomainfrom
FedeZara/refactor/cli-error-reenable-sentry

FedeZara commented Apr 8, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Apr 8, 2026

Uh oh!

claude bot left a comment

Uh oh!

Swimburger Apr 10, 2026

Uh oh!

graphite-app bot Apr 10, 2026

Uh oh!

FedeZara commented Apr 10, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

	export const CliError.Code = {
	export namespace CliError {
	export const Code = {

Conversation

FedeZara commented Apr 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Changes Made

Error codes used

Files touched (grouped by area)

Testing

Uh oh!

github-actions bot commented Apr 8, 2026

🌱 Seed Test Selector

Uh oh!

claude bot left a comment

Choose a reason for hiding this comment

Claude Code Review

Uh oh!

Swimburger Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

graphite-app bot Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

FedeZara commented Apr 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

FedeZara commented Apr 8, 2026 •

edited

Loading

FedeZara commented Apr 10, 2026 •

edited

Loading