Changelog

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.

5.22.0

(feat): Add fern sdk list command to list configured and available SDK generators. Displays configured SDKs from local fern.yml and available generators from the Fern registry. Supports --language, --type, and --json flags.

5.21.1

(chore): Bump IR to 67.2.0 to publish the optional resumable field added to SseStreamChunk in PR #15795. Without the IR version bump, no new @fern-fern/ir-sdk minor was published and the field stayed invisible to downstream consumers.

5.21.0

(feat): Add a new resumable sub-property to the x-fern-streaming OpenAPI extension (and a corresponding resumable field on Fern Definition response-stream blocks). When set on an SSE endpoint, the IR carries resumable: true on the SSE chunk so generators can emit a client-side reconnect loop using standard SSE primitives (Last-Event-ID, retry:).

The flag is inheritable: setting x-fern-streaming.resumable: true at the OpenAPI document level applies to every SSE endpoint unless an operation overrides it (silent fallback). Defaults to false. The IR field is optional, so generators that don’t read it are unaffected.

5.20.1

(fix): Pass GitHub Enterprise host to Fiddle for remote generation so that self-hosted GHE instances are correctly targeted by the remote pipeline.

5.20.0

(feat): Add --fix flag to fern check, fern sdk check, and fern docs check. When specified, the CLI automatically applies known fixes for detected issues (e.g. replacing invalid SDK target versions with the latest stable release, applying deterministic MDX parse error fixes).

5.19.1

(fix): Property-level x-fern-audiences (and Fern definition audiences:) filtering now correctly excludes properties whose audiences do not overlap the active filter and preserves untagged properties as universal — matching endpoint-level audience semantics. Examples are also scrubbed of excluded items: auto-generated jsonExample snapshots, inlined request-body example properties, endpoint example query parameters, and user-specified webhook payload examples.

5.19.0

(feat): Add PR title, body, and commit message to fern automations upgrade --json output. The new pr field in the JSON output allows GitHub Actions consumers to use CLI-generated PR formatting directly, eliminating duplicated presentation logic.

5.18.1

(fix): Fix GitHub Enterprise support for self-hosted SDK generation. Octokit API calls (signed commits, PR creation, ref updates) now use the correct GHE API base URL derived from the repository URI instead of always hitting api.github.com.

5.18.0

(feat): Add fern schema [name] command (CLI v2) that emits a JSON Schema for fern.yml. Running fern schema with no argument prints the full schema; passing a dot-delimited subsection (e.g. fern schema sdks, fern schema sdks.targets, fern schema api) prints just that block. Intended primarily for AI agents that need to generate or validate Fern config at runtime without consulting external docs.

5.17.1

(fix): Fix publish to respect FERN_FDR_ORIGIN environment variable override.

5.17.0

(internal): Attach fern_run_id and github_run_id as PostHog properties on every CLI event so PostHog dashboards can correlate analytics with the FERN_RUN_ID set by the GitHub Actions wrappers and the matching Sentry tags.

5.16.1

(fix): fern check now accepts changelog navigation entries whose URL has any allowlisted segment (e.g. whats-new, release-notes, changelog), not just the trailing one. This means a changelog page like /whats-new/product-updates no longer raises a false-positive error about RSS / Atom / JSON feeds 404ing — the docs server matches the same loosened rule when serving feeds.

5.16.0

(feat): cli-v2: fern check now prints rich, Rust-style errors for MDX/Markdown parse failures. Each error includes a stable error code (e.g. E0301), a --> path:line:col location, two surrounding source lines with a caret pointer, and an inline fix: suggestion when one is available.

(feat): cli-v2: add interactive AI-assisted fixes for MDX/Markdown parse errors. fern check now offers to apply a fix when run interactively — using a deterministic string-replace when the parser’s fix: hint matches the file, and falling back to a configured AI provider otherwise. Provider is selected via fern config ai set-provider <anthropic|openai|bedrock> and credentials via fern config ai set-key <key> (Bedrock uses the standard AWS environment). Prompts are skipped automatically when running inside a Claude Code session (CLAUDECODE=1).

(feat): cli-v2: when fern check finds multiple MDX errors, prompt once for a batch action (“apply all”, “review each”, “skip all”) instead of prompting once per error.

5.15.3

(fix): Fix fern check to respect x-fern-ignore when validating duplicate SDK method names. Operations marked with x-fern-ignore: true are now excluded from the duplicate override check.

5.15.2

(fix): Fix dynamic IR upload and check endpoints to pass correct field names (version, snippetConfiguration) matching the FDR server contract, resolving 500 errors during SDK generation.

5.15.1

(fix): Source org_id on the replay PostHog event from fern.config.json (the project organization slug, like every other CLI flow), not from a Venus token lookup.

5.15.0

(feat): Bake replay initialization into fern generate. Repos with a prior [fern-generated] commit but no .fern/replay.lock now auto-bootstrap inline during the post-generation pipeline — eliminating the need to run fern replay init as a separate step.

5.14.1

(fix): Fix non-deterministic snippet output across runs for SDK generators that consume the dynamic IR (Java, PHP, Python v2, Go v2, Ruby v2, Swift, Rust). The dynamic IR now tags examples with isUserSpecified and emits deterministic example ids; affected generators select examples using the canonical “all user, else first autogenerated” rule, matching TS v1 / Python v1 behavior.

5.14.0

(feat): Emit the replay PostHog event from cloud generation, with surface, org_id, duration_ms, and additional patch counters.

5.13.2

(fix): Improve 429 rate-limit retry logic for remote generation: increase max retries from 3 to 5, respect the server’s retryAfter hint as a minimum delay, and widen jitter (0.2 → 0.5) to reduce thundering-herd retries when many generators run concurrently across multiple API groups.

5.13.1

(fix): Fix dynamic IR upload URLs request passing empty apiId and irVersions parameters, which caused 500 errors from FDR during SDK generation.

5.13.0

(internal): Remove the fern write-translation command. Translation directories under translations/<lang>/ are still respected when loading docs, but the CLI no longer ships a command to generate them.

5.12.0

(feat): fern automations generate now automatically retries 429 Too Many Requests responses with exponential backoff (2s → 120s, up to 3 attempts, jittered). Automation runs are unattended, so transient rate limiting should not fail the run and ask a human to re-trigger with a flag. Real outages still surface as failures after retries exhaust.

(chore): Bump @fern-fern/fiddle-sdk catalog pin to 1.0.2. The new SDK exposes replay on CreateJobRequestV2, so the field added to createJobV3 in PR #15690 stops being silently stripped by the SDK serializer and now actually reaches Fiddle. With this in place, customers setting replay.enabled: false in generators.yml get the legacy GitHub push/PR path on cloud generation. Final activation step for FER-10343.

(feat): Surface CLI errors and warnings as GitHub Actions annotations when running under GHA.

fern automations generate now emits a structured ::error:: workflow command for every failed generator, anchored on the exact line in generators.yml so the annotation appears inline on the file in the PR’s Files-changed view, with the API / group / generator name in the title and the failure reason in the body.

All other commands (e.g. fern generate, fern check) emit annotations from any logger.error / logger.warn call, providing baseline coverage for failures that don’t flow through the per-generator collector. Status-only logs (omitOnTTY) are filtered out so they don’t burn through GitHub’s per-step annotation cap.

5.11.0

(feat): Forward the top-level replay block from generators.yml to Fiddle’s createJobV3 call so cloud generation honors replay.enabled: false and skips the replay pipeline when a customer opts out. Activates once the @fern-fern/fiddle-sdk catalog pin advances to a version that exposes replay on CreateJobRequestV2 (schema landed in fern-api/fiddle#729).

(fix): Fix fern check --api <name> failing when broken-links validation is enabled and docs.yml references multiple APIs. The docs validator now always sees the full set of API workspaces (so the valid-markdown-links rule can resolve every API referenced from the docs navigation), while the --api filter is still applied to API-level validation only.

(chore): Make @boundaryml/baml an optional dependency. The CLI no longer requires BAML to be installed unless AI features (auto-versioning, sdk-diff) are used. Users who invoke AI features without BAML installed will see a clear error message with installation instructions.

5.10.3

(fix): Apply per-locale navbar-links overlays in the default fern docs dev app preview server (the legacy preview and production publish already did this, so dev was the odd one out and showed English CTAs on /<lang>/ URLs). Also matches translation overrides for skip-slug sibling tabs positionally when slug-based matching can’t disambiguate them — without this, only the one tab whose slug retained its own segment got translated.

5.10.2

(chore): Bump axios to ^1.15.1 to address CVE-2026-42037 (CRLF injection in multipart/form-data body via unsanitized blob.type). Narrow the type of the response Content-Type header in init’s OpenAPI URL loader to satisfy axios 1.16’s stricter AxiosResponseHeaders typings.

5.10.1

(chore): Plumb the top-level replay block from generators.yml through the remote generation runner to the createJobV3 wire boundary, so cloud generation can honor replay.enabled once Fiddle exposes the field.

5.10.0

(fix): Fix self-hosted GitHub clone failing with “Invalid username or token” when the user’s ${GITHUB_TOKEN} is an OAuth user token (gho_) or personal access token (ghp_, github_pat_). The clone URL hardcoded the x-access-token: username, which is the format reserved for GitHub App installation tokens (ghs_). Now selects the format based on the token prefix, so both auth modes work.

(internal): Capture PostHog telemetry for replay outcomes during fern generate. Emits a single replay event with action: pipeline_run carrying patch counts, conflict reason buckets, generator/repo context, and pipeline duration. Honors FERN_DISABLE_TELEMETRY (v1) and FERN_TELEMETRY_DISABLED / ~/.fernrc (v2). Adds a structured [replay] info log line and per-bucket conflict debug counts so the same data is visible in stdout. No file paths, patch IDs, or commit messages are emitted; the SDK repo URI is hashed (sha256, 16-char prefix). Wires the previously-no-op v2 TaskContextAdapter.instrumentPostHogEvent so v2-driven generates feed the same event stream as v1. Distinguishes genuine replay crashes from flow: first-generation to keep success-rate dashboards honest.

5.9.0

(feat): Accept branch under github when mode is release in generators.yml. This allows users to configure a non-default branch for release mode in preparation for wiring the field through to the remote generation service.

5.8.2

(chore): Remove break from the supported changelog types so the automated release flow cannot produce a major version bump. Major releases must now be made by editing the relevant versions.yml directly so the breaking change is explicitly acknowledged in review. Validation rejects type: break in unreleased/.

5.8.1

(fix): Add a valid-changelog-slug rule to fern check that errors when a changelog’s effective URL slug is not one of the values served as an RSS/Atom/JSON feed by the docs platform (changelog, changelogs, release-notes, releasenotes, whats-new, whatsnew). Severity defaults to error and can be overridden via check.rules.valid-changelog-slug in docs.yml.

5.8.0

(feat): Add support for a custom robots.txt file in docs.yml. Set agents.robots-txt to a relative filepath and Fern will host the file at /robots.txt on your docs site, overriding the auto-generated default.

(fix): Show a clear, actionable error when the Fern GitHub App is not installed on the target repository instead of the generic “Failed to create job” message.

5.7.10

(fix): Fix the OpenAPI 3.1 -> IR converter to respect endpoint-level security: [] opt-outs when auth is configured in generators.yml. Previously, declaring an auth scheme at the workspace level would silently override every endpoint-level security field — including explicit empty-array opt-outs — so endpoints that intentionally opted out of auth (e.g. an OAuth token endpoint, or a public endpoint) ended up rendered in docs and SDKs as if they required the global auth scheme.

5.7.9

(fix): fern docs dev now fails with a clear error when no docs.yml is present, instead of exiting silently.

(fix): Fix section landing pages with skip-slug: true ignoring frontmatter slug declarations. Sections now compute separate slugs for the overview page (honors frontmatter) and for children (respects skip-slug), so both features work correctly together.

5.7.8

(fix): Fix fern logout showing a “localhost refused to connect” error page by starting a local server to serve a branded confirmation page, matching the login flow. Also update both login and logout confirmation pages with new branded designs.

5.7.7

(chore): Reduce verbose logging during OpenAPI parsing by moving individual example validation warnings to debug level. The per-API example validation summary is still shown at warn level.

(fix): Improve logging when APIs are skipped during docs generation. Skipped APIs now log at error level (instead of warn) with the API name and a clear reason. Repetitive per-endpoint frontmatter warnings are aggregated into a single summary line per API.

5.7.6

(fix): Fix docs preview server showing “ready” message when the server process crashes on startup. The CLI now exits with a clear error message instead.

(fix): On Windows, recover critical standalone node_modules packages (next, react-dom, styled-jsx) when symlink resolution fails due to long .pnpm directory names. The CLI now scans the .pnpm store and copies packages directly as a fallback.

5.7.5

(fix): Send customDomains when publishing docs translations so FDR mirrors the translated blob to every URL the docs are published to. Previously translations were only written under the canonical fern URL, so docs sites served from a custom domain with a basepath (e.g. buildwithfern.com/learn) 404’d on every localized page.

5.7.4

(fix): Strip Windows drive letter prefixes from resolved image paths in docs preview to prevent raw filesystem paths from leaking into rendered HTML on Windows.

5.7.3

(fix): Fix image path resolution on Windows for fern docs dev and fern generate docs. Path utilities (resolve, dirname, join) now normalize output to forward slashes, preventing file ID lookup mismatches caused by mixed path separators on Windows.

5.7.2

(fix): Allow BCP 47 locale tags (e.g. ja-JP, pt-BR, zh-Hans-CN) in the translations and languages fields of docs.yml. Previously these were rejected by the JSON-schema validator with must be one of [en, es, fr, ...].

5.7.1

(fix): Preserve OpenAPI default values for array schemas across query parameters, headers, request bodies, and response body properties so docs can render “Defaults to …” metadata for arrays.

5.7.0

(internal): cli-v2: introduce a shared stdin/stdout abstraction so commands uniformly honor the Unix - marker on I/O flags (stdin for inputs, stdout for outputs), with a “- used at most once per command” guard and a JSON-or-path input helper that parses inline JSON first and falls back to a file read.

(internal): cli-v2: fern api compile --output - now uses the shared stdio helper (behavior unchanged — still streams IR JSON to stdout).

(feat): cli-v2: fern sdk generate --api - and fern sdk preview --api - now read the OpenAPI/AsyncAPI spec from stdin (e.g. cat openapi.json | fern sdk generate --api - --org acme --target typescript --output ./sdk).

(feat): cli-v2: fern api split --output - prints the generated overlay/overrides for the matching spec to stdout as a preview, without modifying the workspace (no git-HEAD restore, no fern.yml updates). Requires --api to select a single spec.

5.6.1

(fix): Fix translated docs pages failing to resolve shared snippets (<Markdown src="..."/> and <Code src="..."/>). Snippet references are now resolved before registering translations, with locale-aware loading that prefers translated snippets (e.g., translations/zh/snippets/foo.mdx) when available.

5.6.0

(feat): Add fern automations upgrade command that wraps fern upgrade and fern generator upgrade into a single invocation with structured JSON output (--json). Designed for consumption by the fern-upgrade GitHub Action.

(fix): Replace brittle hardcoded changelog URL map in upgradeGenerator.ts with a regex-based derivation that supports all current and future generators.