React Hydration Errors (#418, #423) in build-docs Output
Nobody has claimed this yet.
- 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
-
Given this
redocly.yamlfile
Noredocly.yamlfile was used. -
And this OpenAPI file(s)
A minimalopenapi.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
- Run this command with these arguments...
npx @redocly/cli build-docs openapi.yaml -o redoc-static.html
- See error
Open the generatedredoc-static.htmlfile 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
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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