Troubleshooting

ERR_PNPM_IGNORED_BUILDS when running pnpm install

After scaffolding a new project with create-boltdocs, running pnpm install fails with:

[ERR_PNPM_IGNORED_BUILDS] Ignored build scripts: esbuild@0.14.47, sharp@0.34.5

Why this happens

pnpm 10+ blocks lifecycle scripts (preinstall, postinstall, install) from dependencies by default. Packages like esbuild, sharp, and @swc/core require native build scripts to compile platform-specific binaries. Without explicit approval, pnpm refuses to run them.

Fix

If you used create-boltdocs, the template already includes the required configuration. If you're adding Boltdocs to an existing project, add the following to your package.json:

{
  "pnpm": {
    "onlyBuiltDependencies": [
      "@swc/core",
      "esbuild",
      "sharp"
    ]
  }
}

Then run pnpm install again. This tells pnpm to allow build scripts for these specific packages.

Alternatively, you can run pnpm approve-builds interactively to pick which dependencies should be allowed to run scripts.

serve -s shows the home page on every routes

If you're testing the static build locally **with pnpx serve -s ., you might notice that every URL (e.g., /about, /docs/guides) renders the home page instead of the expected content.

Why this happens

The -s (single-page app) flag tells serve to fall back to index.html for any route that doesn't match a file. Because serve does not automatically resolve /about to about.html (or about/index.html) in this mode, the fallback kicks in and serves the root page instead.

Fix

Use serve without the -s flag:

pnpx serve . -l 3000

Without -s, serve correctly resolves URL paths to their corresponding generated HTML files (e.g., /about → about.html, /docs/guides → docs/guides.html).

Production deployments

This issue does not occur on production platforms like Vercel, Netlify, or Cloudflare Pages — they all handle clean-URL-to-file resolution correctly by default. The -s flag behavior is specific to local testing with the serve package.

Custom Feedback throws "body stream already read" error

If your page or code-block feedback form triggers a red validation error stating Failed to execute 'text' on 'Response': body stream already read.

Why this happens

This is caused by client-side response parsing bugs in older versions of the boltdocs core package. When an API route fails (e.g., returns 404 or 500), the client hook attempted to parse the error payload as JSON first and then immediately read it as plain text if it failed, exhausting the response stream.

Fix

Upgrade your boltdocs dependency in package.json to v2.8.4 or later, which correctly clones or reads the stream once:

pnpm add boltdocs@latest

Feedback fails with 404 or 505 in production

When you submit a rating or comment on your live deployed site, the network tab shows that the POST request to /api/feedback fails with a 404 Not Found or 405 Method Not Allowed.

Why this happens

Since Boltdocs builds fully static sites (SSG), there is no backend server running in production to receive POST requests.

Fix

To resolve this, you must set up a serverless function endpoint on your hosting platform to receive the feedback request and forward it to GitHub securely.

• For Vercel: Create a file at api/feedback.ts containing:
  api/feedback.ts

  import { handleVercelFeedback } from 'boltdocs/server'
  export default handleVercelFeedback
  

• For Cloudflare Workers: Create a file at functions/feedback/index.ts containing:
  functions/feedback/index.ts

  import { handleWebFeedback } from 'boltdocs/server'
  export default handleWebFeedback
  

• For Netlify: Create a file at netlify/functions/feedback.ts containing:
  netlify/functions/feedback.ts

  import { handleNetlifyFeedback } from 'boltdocs/server'
  export default handleNetlifyFeedback
  

• For AWS Lambda: Create a file at lambda/feedback/index.ts containing:
  lambda/feedback/index.ts

  import { handleAwsFeedback } from 'boltdocs/server'
  export default handleAwsFeedback
  

• For Environment Variables: Make sure you have configured BOLTDOCS_GITHUB_TOKEN, BOLTDOCS_GITHUB_REPO_OWNER, and BOLTDOCS_GITHUB_REPO_NAME in your deployment settings.
• Local Testing: Test your production builds locally using boltdocs preview (which automatically supports the /api/feedback endpoint) rather than a dummy static server like the serve package.

Custom Feedback throws "GitHub repository coordinates (owner and repo name) are missing"

If your feedback form displays the red validation error: GitHub repository coordinates (owner and repo name) are missing. Please set GITHUB_REPO_OWNER and GITHUB_REPO_NAME.:

Why this happens

The production serverless function runs standalone and does not compile or parse boltdocs.config.ts (to keep the runtime container lightweight and prevent loading heavy dev tools like Vite). Therefore, the function cannot read the coordinates from your config file at runtime.

Fix

You must configure the owner and repository name as environment variables in your hosting provider's settings panel (e.g. Vercel, Netlify, Cloudflare):

• BOLTDOCS_GITHUB_REPO_OWNER (or GITHUB_REPO_OWNER)
• BOLTDOCS_GITHUB_REPO_NAME (or GITHUB_REPO_NAME)

And make sure your local .env file contains:

BOLTDOCS_GITHUB_REPO_OWNER=your-github-username-or-org
BOLTDOCS_GITHUB_REPO_NAME=your-repo-name