[Support Guide] Please help me troubleshoot. What information do I need to share?

Helping us help you

This support guide is about helping us help you when you have troubleshooting questions.

The information required to troubleshoot an issue varies depending on what the issue is. This guide is was made to help you know what information to send us based on what the issue is.

Most important: send exact reproduction steps if possible

The most important thing to send us are the exact steps required to trigger the issue. If you know what will reliably cause the issue to occur, please send us those details. The instructions might look like:

  1. Visit this URL: <URL HERE>
  2. On that page, click on the link “some link”.
  3. At the prompt type “something here”.
  4. Look in the browser dev tools and see that it says “error message” (whatever “error message” might be)

If we have exact instructions that tell us how to trigger the issue, our support team can analyze and research it directly. If we think of new questions, we can go get the answers ourselves. If we can get answers ourselves, we don’t need wait for an answer. This greatly speeds up the troubleshooting processing.

If we need to ask you questions and wait for answers, we are happy to do so instead. However, this is slower than if we can just research the issue directly ourselves.

Note, one thing that does not help us very much is to use example domain names or site names. Please do not send examples with pretend sites or example domain names if you are asking about a real site. We need to know the real URLs, real domain names, and real site names whenever possible. If you want to send that to us privately, please ask us to enable private messaging (PMs) for your support forum login. Note, PMs can only be seen the the person you send them to, so this will also slow down troubleshooting compared to sharing the information publicly.

What information is needed when you don’t have reproduction steps?

Sometimes we cannot see the issue when we test, even with reproduction steps. You can see the issue when you test but our support team cannot. In these cases, we need to get the information from you as only you have access to it.

So, what information does our support team need? The answer depends on what the issue is. I’ll try to provide a quick list of the information need to troubleshoot various types of issues.

Custom domain or SSL is not working

For a custom domain not working or SSL type issue, we need the following details:

Also, if we cannot reproduce using the information above, a “traced lookup” (also called a “recursive lookup”) for the DNS record from your local system might be required.

If you ask me (@luke), the best tool for performing that traced lookup is the tool dig. First you must install dig. Then run the command below replacing <domain name> with the actual domain which isn’t working:

dig +trace <domain name>

For example, if the custom domain which isn’t working is example.com then the command above would be:

dig +trace example.com

Redirects not working

If you have created a redirect and it isn’t working, the following details are needed:

  • the redirect rule as it appears in either _redirects or netlify.toml
  • the URL being requested

Again, for the fastest assistance, please send us the real URL not working. (Again, you can PM that information if you don’t want to share it publicly.)

The build works locally but not at Netlify

The first things to check are if the dependencies and language version used at Netlify match the local build. For example, if you use Node version 16 locally and the build is using Node 12, the Netlify Node version should be changed to match.

If it still doesn’t work or if the language version already are the same, then the following details will be helpful:

  • a link to your repo (only if the repo is public)
  • a link to the deploy logs for the failing build (public or private)
  • the results of a “fresh clone and build” of the repo locally

What is a “fresh clone and build”? Well, your local working directory is not the source of truth for your repository. The upstream repository is the source of truth for anyone (like Netlify) that clones the repo. It is common for an upstream repo to be missing information in the local repo directory. This happens for many different reasons.

You can often reproduce an issue at Netlify in the local system with a “fresh clone” of the repo into new location. If you are able to reproduce the issue locally in a fresh clone, the issue is being caused by your repo itself (and has nothing to do with Netlify).

To make a fresh clone, change to a new empty directory and then do the following:

  • git clone <REPO URL>
  • cd <REPO DIRECTORY>
  • run the install commands for dependencies (which could be npm install, yarn install, gem install)
  • run the build command

If you see the same error in the new directory as you do at Netlify, then the issue isn’t being caused by Netlify. You will need to get the “fresh clone” working locally first before we can troubleshoot.

Summary

We hope this support guide will help make troubleshooting faster by helping us gather all the information needed to troubleshoot quickly.

This topic is likely to evolve over time. If we think of different types of issues, we will add the information needed to troubleshoot that type of issue here.

If you want us to add lists for other types of issues or if you want to discuss any of the lists above (to make suggestion or just to ask questions), please feel free to comment below.

2 Likes