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

Support Support Guides
, , , ,
1

Last Reviewed by Netlify Support Staff: July 2023

Help 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 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 may 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 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: 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 and ID’s whenever possible. Site ID’s are safe to post publicly; attackers cannot leverage that information. If you need to send that to us privately, please ask us how you can do that, but note that this will drastically slow down our debugging and response time. We will be happy to unlist your thread from public view upon request, so our team can see it but others cannot discover it, if you need a bit more privacy.

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:

  • the custom domain being added to the site
  • the site subdomain at Netlify (like example.netlify.app) or the site API ID (API ID is available in Site Settings in our admin UI’s navigation).
  • the public IP address for the DNS resolver your local system is using

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.

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. There is an extensive article on just that process, here: [Support Guide] Debugging Netlify site builds

If it still doesn’t work or if the language versions already are exactly 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