When you try to build your localhost:8000, one or all of the webpages throws a 404 error.
Solutions
Try some of these solutions to figure out what went wrong in your local build.
If you know which file is causing an error, run this command to identify the error:
yarn verify-mdx path/to/file.mdx
This command returns more information about the error than the normal Gatsby output, such as the specific character and line number causing the error.
Let's pretend I've made a changes to multiple docs in my branch. When I try to either run the site locally or access the Netlify build, I get the following error:
Unexpected character = (U+003D) before name, expected a character that can start a name, such as a letter, $, or _/usr/src/app/www/src/content/docs/new-relic-solutions/observability-maturity/uptime-performance-reliability/aqm-implementation-guide.mdx: Unexpected character = (U+003D) before name, expected a character that can start a name, such as a letter, $, or _
The error does tell me that the doc with an error is in /docs/new-relic-solutions/observability-maturity/uptime-performance-reliability/aqm-implementation-guide.mdx. Other than that, all I know is that there is a = character messing things up somewhere. Cool, but this is a NRQL doc, there are a dozens of = characters.
So, I run yarn verify-mdx src/content/docs/new-relic-solutions/observability-maturity/uptime-performance-reliability/aqm-implementation-guide.mdx. This returns the following:
"message": "Unexpected character `=` (U+003D) before name, expected a character that can start a name, such as a letter, `$`, or `_`",
"name": "284:227",
"reason": "Unexpected character `=` (U+003D) before name, expected a character that can start a name, such as a letter, `$`, or `_`",
"line": 284,
"column": 227,
"location": {
"start": {
"line": 284,
"column": 227,
"offset": 19129,
"index": 1
},
"end": {
"line": null,
"column": null
}
},
"source": "remark-mdx",
"ruleId": "unexpected-character",
"fatal": true
}
[
In this case, the relevant info is:
"line": 284,
"column": 227,
and
"source": "remark-mdx",
"ruleId": "unexpected-character",
"fatal": true
This tells me that there is an unexpected character in line 284, column 227. Then I can go to that section of the doc and further troubleshoot, knowing exactly where the error comes from. In this case, I likely just need to wrap a NRQL example in quotes.
Check the changed files for some of these common markdown syntax errors:
Inconsistent indentation of the nav files
Incorrect front matter syntax
If there's apostrophes and colons in frontmatter fields, surround them with quotes to avoid problems.
Missing closed brackets or tags
Poorly formatted image links
Make sure a new line is between each image import statement.
Be careful when renaming images and their filename paths. A mismatch can cause the entire local build to fail.
Be especially careful when dealing with image files that are imported.
Incorrect image filenames
Image filenames are case-sensitive. Using the wrong capitalization results in a missing image in the doc.
Images with encoded values (like %) in the filename can be especially tricky, so try to avoid them.
To stop and restart yarn:
In the terminal, ensure you're in the /docs-website directory.
Hit CONTROL+C to interrupt the yarn process (if a terminal is active).
Run this command to stop all services running on localhost:8000:
In the terminal, ensure you're in the docs-website directory.
Hit CONTROL+C to interrupt the yarn process, if necessary.
In GitHub Desktop, commit any changes needed on your branch, and then switch to the develop branch.
Back in the terminal, run yarn && yarn start.
If the site now builds correctly from the develop branch, the issue is with the changes in your branch. Stop Yarn again, go back to your branch, and troubleshoot.
Run yarn clean to blow away your local cache. This will make your next build slower, so make sure you have time!
In the terminal, ensure you're in the docs-website directory.
Hit CONTROL+C to stop yarn, if necessary.
Begin a new build by running yarn clean && yarn && yarn start.
There may be times when your .cache directory has been corrupted. This directory is ignored by Git, which means that it travels with you from branch to branch. This might be the problem if your local builds are failing regardless of which branch you’re on.
To solve this from your /docs-website directory, run rm -rf .cache.
Starting a build from scratch will blow away all your node modules, hidden .cache folder, and local cache. This takes a long time to run, around 10–20 minutes.
In the terminal, ensure you're in the docs-website directory.
Hit CONTROL+C to stop yarn, if necessary.
Run yarn reboot (or the use Keyboard Maestro command kknuke*).
*If you use the kknuke Keyboard Maestro command, when everything completes, start the site by running yarn start.
Sometimes the local site builds, but pages within the site don't. To fix this issue, try running the local build in a private or incognito session. You can also try clearing out your browser's cache.
Required build checks fail
Problem
When you create a PR, one of the required checks fails to pass.
Note
If an optional check fails, it's okay to merge the PR since optional checks don't block releases. However, if you want to investigate the check further, you can message the help channel so the hero can look into the failure.
Solution
If a check is failing, first try closing and reopening your PR.
Then, rerun the checks:
Go to the PR.
Click Details > Re-run jobs.
If this doesn't work, you'll need to reset the checks, which will force a rebuild of the cache:
In your local repo, find the file gatsby-config.js (or use CMD-P to jump to it fast in VSCode).
Swap the first and second line of code (it doesn’t matter what order these lines are in, except to make the Gatsby Build check rebuild the cache):
const fs = require('fs');
const parse = require('rehype-parse');
Save the file and commit the change to your PR.
Re-run the build checks.
Wait a LOOOOONG time.
PR merge conflicts
Problem
When you try merge a PR from your local branch, you get a merge conflict.
Solution
If you're getting a merge conflict, click Resolve conflict in either Github desktop or browser and review the conflicts line by line. Make sure to get your approver to review your PR after you fix the merge conflict.
Avoiding merge conflicts
Here are some recommendations to avoid merge conflicts:
Before you merge to develop or main, click Fetch origin to make sure you pull down the most up-to-date version of develop or main.
If you’re working on taxonomy changes, fix your merge conflict as soon as possible. If your branch lingers for a while, it can get outdated from develop pretty fast and that can cause some unexpected issues.
If you get a conflict merge from what's new posts, it's because the whats-new-ids.json file (which is automatically updated when the site builds) can get out-of-date pretty fast.
Caution
Never merge a PR that changes whats-new-ids.json. If you see changes to the whats-new-ids.json file show up in GitHub Desktop, make sure to discard them rather than push them up to your branch. This will make it less likely that other people will have to deal with merge conflicts related to this file.
Port 8000 is unavailable
Problem
When you try to run yarn start, the terminal responds:
Something is already
running at port 8000. Would you like to run the app at another port instead?
Solution
To stop all services running on localhost:8000, run this command in your terminal:
When you click on a redirect link in your local build, you get a 404 error.
Solution
Redirects take a long time to load in a local build. When you click on a redirect, wait until it throws a 404, and then wait ~1-2 minutes. It should redirect you after a while. If it doesn’t, check the markdown syntax to ensure you set up the redirect correctly.
You can also test the redirects out in the Gatsby build.
SSH authentication fails
Problem
When you try to push commits to your remote branch, you get an SSH authentication error.
Solution
Sometimes signing in/out of of Github Desktop can fix an authentication issue:
In the top menubar, go to Preferences.
Sign out and sign in again.
If this doesn't work, try to push commits to your remote branch. If it still fails, try manually pushing your PR using the terminal. For example, to push the PR second-kafka-pr-for-issue-11231, run this command:
If you have an SSH issue, the terminal will return an authentication error message. If the response to this command prompts you for a passphrase, your SSH was somehow confused. By entering your passphrase, you should be back in business. If you can’t remember your passphrase, check out this article.