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

[FedeZara]

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

• chore(cli): rename FernCliError to TaskAbortSignal #14746 — rename FernCliError to TaskAbortSignal (clears the naming space)
• chore(cli): make instrumentPostHogEvent synchronous #14747 — make CLI v1 telemetry synchronous (so failWithoutThrowing can report errors)
• chore(cli): eagerly resolve TelemetryClient distinctId via async factory #14748 — make CLI v2 telemetry synchronous (same, for CLI v2)

Follow-up PRs

• chore(cli): temporarily disable Sentry reporting for unclassified errors #14750 — temporarily disable Sentry for unclassified errors (safety net while migrating)
• chore(cli): migrate @fern-api/cli to use CliError #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)
• chore(cli): re-enable Sentry reporting for unclassified errors (fallback to InternalError) #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

• Updated test helpers and mocks for new CliError / MockTaskContext signatures
• Existing CLI v1 and v2 tests pass

---

[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.}

[github-actions]

🌱 Seed Test Selector

Select languages to run seed tests for:

• Python
• TypeScript
• Java
• Go
• Ruby
• C#
• PHP
• Swift
• Rust
• OpenAPI
• Postman

---

How to use: Click the ⋯ menu above → "Edit" → check the boxes you want → click "Update comment". Tests will run automatically and snapshots will be committed to this PR.

[amckinney]

Nice 👍

[amckinney]

This supersedes the handling that was previously in packages/cli/cli/src/cli.ts, right?

[FedeZara]

Exactly, I moved it here to have a single handling place. The behavior should be the same as before, but I'll check with some testing.

[FedeZara]

To make it simple, it's now resolveErrorCode responsible of categorizing the error and understand what we should do with it.

[amckinney]

Do we need to capture task events separately? We have the same command name, so I don't know how valuable this would be. It looks like we didn't have this before, right?

[FedeZara]

I'm sending PostHog events also here because the error that will surface to the CLI main catch clause will be a generic TaskFailureSignal that is not being tracked anymore in PostHog. The behavior will change a little compared to the current, but we'll have better error categorization thanks to this change (before we would capture generic TaskFailureSignal in most of the cases)

[FedeZara]

Let me know if you agree on the change or you want this to be consistent with the past

[Swimburger]

one thing we often do is create a namespace with the same name as the class, then exported types from it.
So you could do

import { CliError } from "...";

const code = CliError.Code.ConfigError;

Example from Claude on how to do this.

export class CliError extends Error {
    public readonly code: CliError.Code;

    public constructor(message: string, code: CliError.Code) {
        super(message);
        this.name = "CliError";
        this.code = code;
    }
}

export namespace CliError {
    export type Code = (typeof Code)[keyof typeof Code];
    export const Code = {
        ConfigError: "ConfigError",
        NetworkError: "NetworkError",
        AuthError: "AuthError",
    } as const;
}

[graphite-app]

Type CliErrorCode does not exist in the exported API. The correct type is CliError.Code.

This will cause a TypeScript compilation error because @fern-api/task-context exports CliError with a nested Code type, not a separate CliErrorCode type.

Fix:

import { type CliError } from "@fern-api/task-context";

Then update the parameter types on lines 82 and 88 from:

_options?: { code?: CliErrorCode }

to:

_options?: { code?: CliError.Code }

Suggested change

	type CliErrorCode,
	type CliError,

Spotted by Graphite



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

[github-actions]

SDK Generation Benchmark Results

Comparing PR branch against latest nightly baseline on main (2026-04-14T04:55:49Z).

Full benchmark table (click to expand)

Generator	Spec	main (generator)	main (E2E)	PR (generator)	Delta
csharp-sdk	square	92s	127s	89s	-3s (-3.3%)
go-sdk	square	90s	137s	103s	+13s (+14.4%)
java-sdk	square	173s	187s	163s	-10s (-5.8%)
php-sdk	square	84s	122s	88s	+4s (+4.8%)
python-sdk	square	128s	163s	126s	-2s (-1.6%)
ruby-sdk-v2	square	113s	156s	117s	+4s (+3.5%)
rust-sdk	square	96s	92s	94s	-2s (-2.1%)
swift-sdk	square	86s	129s	84s	-2s (-2.3%)
ts-sdk	square	101s	136s	102s	+1s (+1.0%)

main (generator): generator-only time via --skip-scripts (includes Docker image build, container startup, IR parsing, and code generation — this is the same Docker-based flow customers use via fern generate). main (E2E): full customer-observable time including build/test scripts (nightly baseline, informational). Delta is computed against generator-only baseline.
⚠️ = generation exited with a non-zero exit code (timing may not reflect a successful run).
Baseline from nightly runs on main (latest: 2026-04-14T04:55:49Z). Trigger benchmark-baseline to refresh.
Last updated: 2026-04-14 18:33 UTC

[devin-ai-integration]

Devin Review found 1 new potential issue.

View 17 additional findings in Devin Review.

[devin-ai-integration]

🟡 Double lifecycle events in cli-v2 when TaskContextAdapter.failWithoutThrowing is called without a subsequent throw

In cli-v2, TaskContextAdapter.failWithoutThrowing at line 73 now calls reportError, which sends a PostHog lifecycle event with status: "error". If the command handler doesn't throw after this call (e.g., a legacy function calls failWithoutThrowing and then returns normally), execution continues to the success path in withContext.ts:33-36, which sends a second lifecycle event with status: "success". This results in contradictory duplicate lifecycle events for a single command invocation — one error and one success — polluting analytics data.

Prompt for agents

The issue is that reportError (called from TaskContextAdapter.failWithoutThrowing at line 73 of TaskContextAdapter.ts) sends a lifecycle event unconditionally, and then the withContext.ts success/error path sends another one. The lifecycle event should only be sent once per command invocation.

Possible approaches:
1. Track whether a lifecycle event has already been sent on the Context object (e.g. a boolean flag), and skip the duplicate in reportError or withContext.ts.
2. Only send the lifecycle event from withContext.ts (top-level), not from reportError. The reportError function would only handle Sentry reporting. This requires splitting the current reportError into Sentry-only and lifecycle+Sentry variants.
3. Have the reportError called from failWithoutThrowing only send Sentry (not lifecycle events), and leave lifecycle event sending exclusively to the withContext.ts catch/success blocks.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[FedeZara]

Merge activity

• Apr 14, 6:41 PM UTC: @FedeZara merged this pull request with Graphite.