GitHub troubleshooting

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

GitHub authentication fails

If you suddenly find that you can no longer push to your remote branch in GitHub Desktop, you may have developed a problem with SSH.

If logging out of GitHub Desktop via Preferences doesn’t seem to help, you can confirm if you have an SSH issue by switching to the command line and trying to push manually. For example: git push --set-upstream origin second-kafka-pr-for-issue-1123

If 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.

My build is failing mysteriously

Here’s a few things you can check if your build is failing:

• Indenting in the nav files
• Front matter
  • 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
  • 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.
• 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, try to avoid them.

Issues with the local site

If you're running with issues with your local build, try these options:

My redirect throws a 404 error when testing it locally

Redirects are a bit strange on local builds. To test them, navigate to the page that is being redirected, wait until it throws a 404, and then wait ~1-2 minutes. It should redirect you after a while. If it doesn’t, ensure you set up the redirect correctly.

You can also test the redirects out in the Gatsby build.

A check fails in the PR

Rarely, a build or check will fail due to some internal error. You can re-run the check by going to the PR, clicking Details, and then clicking Re-run jobs.

If that doesn't fix it, you probably have genuine build errors. Pull down locally and troubleshoot.

Reset the 'build the docs site' build check

There are times when this check fails. If this happens after your local builds have built successfully, you may need to force a rebuild of the cache.

1. In your local repo, find the file gatsby-config.js (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.

Troubleshoot merging conflicts

Merge conflicts can seem pretty scary, but it’s ultimately just deciding between two different versions of a doc. Here are some tips on how to get through it.

• Fix your merge conflict as soon as possible. Especially if you’re working on taxonomy changes. If your branch lingers for a while it can get outdated from develop pretty fast and that can cause some unexpected issues.
• Check your fix locally to make sure that it looks good there.
• Ask your PR approver to review your PR after you fix the merge conflict.

Here are two options to resolve conflicts:

• When you see the conflicts in GitHub desktop, click the option to resolve these in VS Code.
• Use the GitHub website editor (click the Resolve conflict button) to fix these.

What’s new related merge conflicts

Merge conflicts pop up pretty often with what’s new posts because the whats-new-ids.json file that’s automatically updated when the site builds can get out-of-date pretty fast.

If you see changes to this 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.