• EnglishEspañol日本語한국어Português
  • Log inStart now

GitHub troubleshooting

Are you having problems working on a doc in GitHub? Check out the following common issues.

Local build throws 404 error

Problem

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.

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:

  1. Go to the PR.
  2. 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:

  1. In your local repo, find the file gatsby-config.js (or use CMD-P to jump to it fast in VSCode).

  2. 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');

  3. Save the file and commit the change to your PR.

  4. Re-run the build checks.

  5. 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:

kill -9 $(lsof -i TCP:8000 | grep LISTEN | awk '{print $2}')

Redirect link throws 404 error

Problem

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:

  1. In the top menubar, go to Preferences.
  2. 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:

git push --set-upstream origin second-kafka-pr-for-issue-1123

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.

Copyright © 2024 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.