Changelog

5.33.7

(fix): Handle null OpenAPI overlay files as validation failures instead of allowing them to throw internal TypeErrors during workspace loading.

5.33.6

(fix): Classify missing readme endpoint references in generators.yml as configuration errors.

5.33.5

(fix): Classify unresolved Fern response type references as validation errors instead of reportable internal resolution failures.

5.33.4

(fix): Add retry logic to the air-gap health check so that transient network failures (DNS blips, momentary connectivity drops) no longer cause false air-gapped mode detection. The check now retries up to 3 times with backoff before declaring air-gapped mode. Also logs the underlying error cause for better debugging.

5.33.3

(fix): Swallow stdout/stderr EPIPE events in the cli-v2 terminal logger so Unix pipe closures do not report false-positive internal errors.

(fix): Stop reporting invalid endpoint server references during IR-to-FDR conversion to Sentry.

(fix): Prevent CLI telemetry from failing when the user’s home directory cannot store Fern’s analytics ID.

5.33.2

(fix): Validate that the Fern instance url and every custom-domain share the same basepath when basepath-aware mode is enabled (multi-source: true or the deprecated experimental.basepath-aware: true). Previously the check was skipped when the custom domain was at the root, allowing publishes that would 404 after DNS cutover.

(fix): Strip any https:// or http:// prefix from custom-domain entries in docs.yml before they’re sent to FDR or used for basepath comparisons. Including the protocol in the configured value could interfere with basepath resolution during DNS cutover.

5.33.1

(chore): Publish a JSON Schema for fern.yml so YAML language servers can provide autocomplete and validation in IDEs. Regenerate via fern schema --output (or pnpm fern-yml:jsonschema in the monorepo).

5.33.0

(feat): Mount pre-processed API specs into generator Docker containers. Specs are bundled, overrides merged, overlays applied, x-fern-ignore operations filtered, and x-fern-audiences respected before outputting compact JSON to generators. Add hidden resolve-specs command.

5.32.1

(chore): Bump @fern-api/generator-cli to 0.9.33 (picks up @fern-api/replay 0.16.1).

5.32.0

(feat): Support structured x-fern-base-path with per-parameter declarations and defaults. The OpenAPI extension now accepts an object form with path and parameters, where each parameter can specify a type, docs, and default.

5.31.0

(feat): Populate hasWebSocketInTree on IR Package/Subpackage types. When a subpackage (or any of its nested children) contains a WebSocket channel, this field is set to true, enabling generators to wire WebSocket-only namespaces into the root client.

5.30.4

(fix): Fix the OpenAPI importer silently dropping the request body of an operation that combines x-fern-streaming (with stream-condition) with a oneOf or anyOf request body schema. Endpoints whose body is a plain object (properties/allOf) are unaffected.

5.30.3

(fix): Fix a TypeError: Cannot read properties of undefined (reading 'startsWith') crash in the OpenAPI parser when an operation’s x-fern-streaming extension sets only resumable: true (or otherwise omits both format and stream-condition). The parser now returns undefined for that operation instead of crashing.

5.30.2

(fix): Fix fern docs link check disconnecting on large sites by using batched requests instead of a single long-lived SSE connection. Pages are now scraped in batches of ~200 and links checked in batches of ~500, with automatic retries on connection failures.

5.30.1

(fix): Fix broken link checker to validate links in pages referenced via folder entries in docs.yml navigation.

5.30.0

(feat): Add commit-and-release mode support for self-hosted GitHub configuration. Users can now set mode: commit-and-release in their self-hosted github: block to commit directly to a branch and create a GitHub release.

5.29.0

(feat): Port the hidden fern docs md command group from CLI v1 to CLI v2. Adds fern docs md generate (beta library documentation generation from source code) and fern docs md check (MDX-only syntax validation) with CLI v2’s consistent UI.

5.28.3

(chore): Add bin/ property to CLI v2 Cache class for shared tool binaries (buf, protoc-gen-openapi) at ~/.fern/bin/, enabling both CLI v1 and CLI v2 to share the same binary download location.

5.28.2

(chore): Generator-cli now delegates divergent-merge recovery (squash-merge of a regen PR, force-push past a generation, lost-then-found generations) entirely to @fern-api/replay’s derived scan boundary. Customers no longer hit the pre-replay precondition gauntlet that occasionally got stuck on stale fern-generation-base tag pointers. Replay still writes the tag for backward compatibility with older bundled generator-cli versions.

5.28.1

(fix): Fix global theme merge to deep-merge object fields instead of overwriting them. Local-only sub-fields (e.g. logo.right-text, logo.height) are now preserved when the global theme defines sibling fields on the same object.

5.28.0

(feat): Consolidate all CLI v2 cache directories into ~/.fern/. Docs preview bundles are now managed under ~/.fern/v1/docs-preview/ and discoverable via fern cache show and fern cache clear --docs-preview. The fern cache clear command never touches the user’s auth token or telemetry ID.

5.27.8

(fix): Fix property-level x-fern-audiences filtering breaking error type resolution when enableUniqueErrorsPerEndpoint is true. Types referenced via object properties (e.g. ErrorResponse → ErrorResponseError) are now correctly included during audience filtering, resolving “Failed to find ErrorResponseError” errors in fern check and fern docs dev.

5.27.7

(chore): Bump @fern-api/generator-cli to 0.9.30, which includes @fern-api/replay 0.15.2 with a fix for customer commits on merged regen branches surviving replay detection.

5.27.6

(chore): Bump @fern-api/generator-cli to 0.9.29, which includes @fern-api/replay 0.15.1 with fixes for fallback patch anchoring, composite-patch survival, and FileOwnership divergence.

5.27.5

(fix): Wrap replaceImagePathsAndUrls calls in DocsDefinitionResolver and previewDocs with try/catch boundaries that convert MDX parse failures to CliError(ParseError), preventing user-authored MDX syntax errors from reaching Sentry as false-positive InternalErrors.

5.27.4

(fix): Classify service and environment errors at their boundary call sites: mark exhausted 429 retries as NetworkError, pass error objects through failWithoutThrowing in remote generation so CliError codes propagate, and reclassify docs preview server startup failures as EnvironmentError instead of InternalError.

5.27.3

(fix): Wrap yaml.load calls in getVersionedNavigationConfiguration and getNavigationConfiguration with try/catch boundaries that convert YAML parse failures to CliError(ParseError), preventing user-authored YAML syntax errors in version and product config files from reaching Sentry as false-positive InternalErrors.

5.27.2

(fix): Suppress Sentry false positives for ENOTEMPTY/ENOMEM syscalls, undici fetch-failed TypeErrors, and errno codes on error.cause.

5.27.1

(fix): Report escaped fatal CLI errors through telemetry in packaged production runs.

5.27.0

(internal): Enrich CLI telemetry with automation-mode context (config repo, branch, commit sha, PR number, trigger, and GitHub run details) on every PostHog event and Sentry error report. Add the three-leg failure flow (Sentry + PostHog + automation event API) so automation-run failures surface end-to-end.

5.26.5

(fix): Suppress additional Sentry false positives for interrupted syscalls, invalid versions, YAML parse failures, IR schema parse failures, invalid GitHub repository config, replay resolve failures, missing translation directories, and global theme fetch failures.

5.26.4

(fix): Fix missing-redirects causing fern check to exit with code 1 even when the rule is configured at warn. Rule initialization failures now honor the configured severity (warn emits a warning, error emits an error) instead of always being reported as fatal. The missing-redirects rule also degrades to a warning when the local docs navigation fails to resolve, captures the underlying failAndThrow message so the warning explains why (e.g. Folder not found: ...) instead of [object Object], and non-Error throws are formatted readably across the validator.

5.26.3

(fix): Fix fern docs dev grabbing the local fern token for authentication when loading a global theme

5.26.2

(fix): Fix commit author attribution for GitHub Enterprise: API-created commits now use the Fern bot identity instead of the PAT-owning user, matching the git CLI behavior of Fern 3.x generators.

(fix): Authenticate Venus calls during local Docker generation (fern generate --local) by silently picking up an existing FERN_TOKEN env var or saved login token, matching the remote generation path. Previously, useLocalDocker skipped the auth flow entirely, leaving Venus calls (e.g. GET /organizations/{org_id}) unauthenticated.

5.26.1

(fix): Forward --verify through the remote (Fiddle) generation path. Previously the CLI-level --verify flag only worked for local generation; on remote runs the value was silently dropped before reaching CreateJobRequestV2.verify. The flag now plumbs through runRemoteGenerationForAPIWorkspace → runRemoteGenerationForGenerator → createAndStartJob and is set on the Fiddle job request, enabling the generator-cli pipeline’s VerificationStep against the language-specific validator on opted-in runs.

5.26.0

(feat): Add fern docs link check command to validate links on live documentation sites. Supports text, JSON, and CSV output formats via --output flag. Use --url <url> to specify which docs site to check, or auto-detect from docs.yml.

(feat): Add progress bars matching fern docs dev style for fern docs link check. Broken links show status codes, blocked links show diagnostic details, and error messages include actionable context.

(feat): The fern docs link check command now resolves broken link sources to local file paths when the server provides sourcePageIds and a Fern workspace is available.

5.25.0

(feat): Register the new fernapi/fern-cli generator in the CLI configuration.

5.24.2

(fix): Fix fern config migrate producing wrong file path references in the generated fern.yml. Paths from generators.yml (relative to the fern/ directory) are now correctly re-rooted to be relative to the project root where fern.yml is created. This also fixes the docs $ref pointer to use ./fern/docs.yml instead of ./docs.yml.

5.24.1

(chore): Propagate Fern docs: strings into generated JSON Schemas so editor hovers work for schemas served from schema.buildwithfern.dev.

5.24.0

(internal): Plumb verify, verifyRunner, and verifyValidatorVersion flags through GenerationRunner.RunArgs so the seed runner can invoke PostGenerationPipeline with VerificationStep and exercise the same validator-container code path that fern generate --local --verify uses. No customer-facing CLI behavior change — the flags are opt-in and used only by the seed test runner today.

5.23.6

(fix): Fix fern docs dev hot reload not working for .mdx file changes. The backend now updates the docs definition before notifying the browser to refresh, and the reload handler properly recovers from errors instead of silently blocking all future reloads.

5.23.5

(fix): Fix SDK generation crashing with fatal: <sha> is not a valid object when the prior fern-bot PR was squash-merged and its branch deleted. The stale fern-generation-base tag update is now skipped with a warning; the SDK PR still opens.

5.23.4

(fix): Fix allOf composition so inline elements with real constraints (e.g. pattern, minLength) produce a properly merged type instead of being silently dropped. Also refactored the allOf shortcircuit logic to use a metadata allowlist, which is safer against new OpenAPI fields.

(fix): Fix example generation for allOf compositions to merge base schema fields into property overrides. When an allOf override specifies only items without type: array, the base schema’s type is now correctly inherited, producing properly typed examples instead of null.

5.23.3

(fix): Property-level x-fern-audiences filtering now also applies on the V3 OpenAPI / AsyncAPI / OpenRPC import path used by fern docs dev and fern generate --from-openapi. Inline request-body properties, query parameters, inline webhook payload properties, named-type properties, v2RequestBodies, and the docs v2Examples blocks (type-level, request body, response body, endpoint-level, v2Responses, and webhook payload examples) are now scrubbed using the same exclusion semantics as the Fern Definition path. Untagged elements remain universal and are never silently removed.

5.23.2

(fix): Suppress Fern’s platform User-Agent header in generated SDKs when the API definition declares a global User-Agent header (case-insensitive) under api.headers. This allows customers to fully override the SDK User-Agent via their Fern Definition without the auto-generated <package>/<version> value also being emitted.

5.23.1

(fix): Fix fern docs dev hanging indefinitely on Node.js v26+ on Linux by disabling io_uring in the child server process. Node 26 enables io_uring by default in libuv, which has a busy-loop bug where worker threads spin on an internal eventfd, starving the main event loop.

5.23.0

(internal): Add an opt-in VerificationStep to the post-generation pipeline that runs .fern/verify.sh (when emitted by the generator) inside a language-specific {generatorImage}-validator container after replay and before any GitHub push. A failing script aborts the pipeline before opening a PR and surfaces raw stderr through the pipeline logger; a missing script is a silent no-op.

The step is gated on a hidden --verify flag for fern generate; when passed (with --local or --runner), the local workspace runner sets config.verify.enabled = true on the pipeline and the configured container runtime (docker or podman) is forwarded to the validator container. Remote/Fiddle generation does not honor this flag yet.

5.22.1

(fix): Fix fern docs dev failing with pnpm 11 due to esbuild build scripts being blocked by default. Writes onlyBuiltDependencies config to the bundle folder before installing esbuild.