General Troubleshooting Best Practices

Knowledge Articles
1

Overview

This knowledge article explains the general best practices for troubleshooting in case an “exact match” knowledge article or official documentation cannot be found.

Applies To

  • Troubleshooting
  • Support

Solution

1. Attach a list of helpful information

The information below is essential to narrow down the cause of the problem and expedite the resolution. If attached to the support case, Support Engineers can recognize the situation and start the investigation smoothly.

1-1. Frequency and impact

Describe the number/ratio of end users impacted and the reproduction rate.

  • How many end users are impacted?
    • e.g., “X out of 100 or X% of users cannot log in”
  • What is the reproduction rate?
    • e.g., “When tried with a testing account, the issue reproduced 100%” or “The application log says the issue happens X out of 100 or X% of total API requests”

Explaining the business impact can help Support Engineers with appropriate prioritization.

  • e.g., “End users cannot log in while the Black Friday campaign is ongoing, resulting in loss of sales opportunities”

1-2. Symptom

Describe the characteristics of the issue.

  • When and where did the issue happen?
    • e.g., “When an end user tried to log in on the Universal Login page” or “When an application hits the Management API’s create user endpoint”
  • What is the error message that end users or applications receive?
    • e.g., “End users see the error message on the Universal Login saying ‘Wrong username or password.’” or “The application receives the HTTP status code 429 Too Many Requests”

1-3. Reproduction

Try to reproduce the issue if possible. Explain the required conditions and reproduction steps.

  • How can the issue be reproduced?
    • See the example below
  • What are the Auth0 entities involved?
    • Name/Id of Applications, Connections, Actions, etc.
  • What is the name and version of the SDK used to build the application?
    • e.g., nextjs-auth0 v.4.5.1
  • Can the issue be reproduced with simple quickstart codes?

For example,

Tenant: my-test-tenant (in the US-3 region)

Application: nextjs-test

SDK: nextjs-auth0 v.4.5.1

Reproduction steps:

  1. Create a simple Next.js application using this example: Add Login to Your Next.js Application
  2. Open a private browsing window to start a new session
  3. Hit the login route on the application side and navigate to Auth0’s Universal Login Page
  4. Bookmark the URL of the Universal Login Page
  5. Log in using a database connection
  6. Log out of the application
  7. Try to log in by visiting the URL bookmarked on Step 4
  8. The end user sees the error message “invalid_request: You may have pressed the back button, refreshed during login, opened too many login dialogs, or there is some issue with cookies, since we couldn’t find your session. Try logging in again from the application, and if the problem persists, please contact the administrator.”

1-5. Network logs

If the issue can be observed on the frontend, capture the network logs.

See: Generate and Analyze HAR Files

1-6. Expectation

Describe the expected vs. actual outcome.

For example, in the case described in the (3) Reproduction section,

Expected: The user can see the Universal Login page and input their username and password again.

Actual: The user sees the above error message.

2. Narrow down the scope of the problem

Use the best practices below when trying to narrow down the problem. Reducing the “moving parts” by leveraging these practices is essential.

2-1. Use a quickstart example to test

Auth0 Quickstarts: https://auth0.com/docs/quickstarts

Build a simple application using a quickstart example, connect it with an Auth0 tenant, and see if the issue still happens.

This approach effectively shows which side the problem originates from (the application vs. the Auth0 server)

2-2. Remove irrelevant codes, features

Code problems:

Say a block of code is not working as expected, throwing an unhandled error, but the exact line causing the issue has not yet been identified.

In such a case, remove some part of the code block and run it again. While the problem still happens, keep doing the same.

  • If the code block becomes small enough and the problem still happens, that is the minimal reproduction condition.
  • If the problem stops happening at some point, the cause likely lies in the part that was just removed in the previous step.

Configuration problems:

The same approach can be applied to configuration problems.

Say a login flow uses a list of features, like MFA, Flexible Identifiers, Actions, Forms for Actions, some feature flags, etc.

If there is a clone/testing environment that can reproduce the issue, remove a feature used for the login flow one by one to find the one that produces the problem.