Skip to main content
The canonical version of the contributor troubleshooting guide lives at docs.github.com/contributing/setting-up-your-environment-to-work-on-github-docs/troubleshooting-your-environment. This page covers engineering-specific issues not addressed there.

​
Failed status checks

If a required check fails on your PR, read the full log before asking for help. Most failures have a specific error message that points to the root cause.
The content linter enforces style and structure rules on Markdown files. Run it locally to see the same errors CI sees:
npm run lint-content -- --paths content/path/to/file.md
Common causes:
  • Incorrect heading hierarchy (skipping from ## to ####)
  • Use of raw HTML instead of Liquid or Markdown equivalents
  • Broken internal links
  • Missing or invalid frontmatter fields
Run the linter on the entire content directory to catch all issues:
npm run lint-content
Run the type checker locally to reproduce the error:
npm run tsc
This runs tsc --noEmit and reports all type errors without emitting output files.
Run the failing test suite locally using the subject name:
npm test -- src/SUBJECT/tests
For fixture-dependent tests, use:
npm run fixture-test -- src/fixtures/tests
See Testing for the full list of test aliases.

​
Stalled status checks

A status check that never starts (stuck in “queued” state) is different from one that fails.
  • Required checks that never start may indicate a workflow concurrency issue. Cancelling the stuck run and re-running it often resolves this.
  • The merge queue check can stall if a PR earlier in the queue has a blocking failure. Check the merge queue status page for the repository.
  • If a check is stuck for more than 30 minutes, ping @github/docs-engineering in #docs-engineering.

​
Node.js version issues

The project requires Node.js version 24 or higher, as specified in package.json: 
"engines": {
  "node": "^24"
}
If you see unexpected errors on startup or during tests, verify your Node.js version: 
node --version
Use a version manager like nvm or fnm to switch versions: 
nvm use 24
# or
fnm use 24

​
Build failures

If npm run build fails:
1

Clear the Next.js cache

rm -rf .next
2

Reinstall dependencies

rm -rf node_modules && npm ci
3

Run the build again

npm run build
Check the error output carefully — Next.js build errors often include the file and line number of the problem.

​
Search not working locally

The search feature requires a running Elasticsearch instance. Without it, search returns no results and test:search fails. 
# Start Elasticsearch locally (Docker)
docker run -p 9200:9200 \
  -e "discovery.type=single-node" \
  docker.elastic.co/elasticsearch/elasticsearch:8.19.1
The Elasticsearch version must match @elastic/elasticsearch in package.json (currently 8.19.1). Once running, set the URL in your environment: 
ELASTICSEARCH_URL=http://localhost:9200/ npm run test:search
For a full local search experience, you also need to index content: 
npm run index-general-search

​
Pages returning 404 locally

A page returns 404 if it exists as a Markdown file but is not listed in the children frontmatter of its parent index.md. Check the parent directory’s index.md for a children: list. If your file is not in that list, add it: 
---
title: My section
children:
  - /my-section/existing-page
  - /my-section/your-new-page   # Add this
---
This is enforced by the content linter. A missing children entry will also cause a lint failure in CI.

​
Missing content after auto-sync

If content is missing after running a sync script (REST, GraphQL, webhooks), check:
  1. The sync script completed without errors
  2. The generated files in src/*/data/ were updated
  3. Your local server was restarted — the dev server does not hot-reload data files in all cases
Restart the dev server after running any sync script: 
npm start

​
Debugging the local server

For an interactive debugger session: 
npm run debug
This starts the server with --inspect and NODE_ENV=development. Attach a debugger using the Node.js inspector protocol (Chrome DevTools or VS Code).

​
Getting help

Open an issue

For bugs, unexpected behavior, or persistent failures. Use github/docs-engineering for engineering issues.

Docs Engineering Slack

For internal staff: post in #docs-engineering. For urgent issues affecting production, tag @github/docs-engineering.

Build docs developers (and LLMs) love

Get started for freeTalk to us