Redocly / Redocly/redoc

React Hydration Errors (#418, #423) in build-docs Output

Open
#2,734 5 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Type: Bug
Dominant language
TypeScript
Stars
25.9k
Forks
2.4k
Avg merge
13h 10m
Merged PRs (30d)
4

Description

Describe the bug

The static HTML file generated by the redocly build-docs command produces React hydration errors (#418 and #423) when opened in a browser. While the page content appears to render, these errors indicate a potential issue in the client-side rendering process. The issue persists across different versions of @redocly/cli.

To Reproduce

  1. Given this redocly.yaml file
    No redocly.yaml file was used.

  2. And this OpenAPI file(s)
    A minimal openapi.yaml:

openapi: 3.0.0
info:
  title: Simple API
  description: A simple API to demonstrate OpenAPI 3.0
  version: 1.0.0
paths:
  /users:
    get:
      summary: Returns a list of users.
      description: Optional extended description in CommonMark or HTML.
      responses:
        '200':
          description: A JSON array of user names
          content:
            application/json:
              schema: 
                type: array
                items: 
                  type: string
  1. Run this command with these arguments...
npx @redocly/cli build-docs openapi.yaml -o redoc-static.html
  1. See error
    Open the generated redoc-static.html file in a web browser and view the developer console.

Expected behavior

The documentation should render correctly without any errors appearing in the browser's developer console.

Logs

Uncaught Error: Minified React error #418; visit https://reactjs.org/docs/error-decoder.html?invariant=418 for the full message or use the non-minified dev environment for full errors and additional helpful warnings.

Uncaught Error: Minified React error #423; visit https://reactjs.org/docs/error-decoder.html?invariant=423 for the full message or use the non-minified dev environment for full errors and additional helpful warnings.

OpenAPI description

A minimal OpenAPI 3.0.0 description was used, as provided in the "To Reproduce" section. No redocly.yaml configuration file was used.

Redocly Version(s)

2.7.0 (the issue was also reproduced with 2.6.0).

Node.js Version(s)

  • Node.js: v22.19.0
  • npm: 10.9.3

OS, environment

Linux Mint 22.2

Additional context

As a point of comparison, the legacy redoc-cli package successfully bundles the exact same openapi.yaml file without producing any console errors.

Command used:

npx redoc-cli bundle openapi.yaml -o redoc-static.html
Image

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by running npx @redocly/cli build-docs openapi.yaml -o redoc-static.html with the minimal OpenAPI file from the issue, then inspect the generated HTML and browser console for React errors 418 and 423. Compare the result with the legacy npx redoc-cli bundle command; done means the build-docs output renders without hydration errors.

Written by the indexing model from the issue text.

Assessment

Tech stack
node.js, react, typescript
Domain
documentation, frontend
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
43/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.