The 401 Unauthorized Error is an HTTP response status code indicating that the client could not authenticate a request.
In this article, we’ll examine the 401 Error in more detail. We'll show you how to diagnose and debug this error within your own application.
Server- or Client-Side?
All HTTP response status codes in the 4xx category are client error responses. These messages contrast with server error responses in the 5xx category, such as the 503 Service Unavailable Error.
However, the appearance of a 401 error code or any 4xx error doesn't necessarily mean the client is the issue, where the client is the web browser or device used to access the application.
For example, if you're trying to diagnose an issue with your application, you can ignore most client-side code. This includes HTML, cascading style sheets (CSS), client-side JavaScript, etc.
On the other hand, this doesn't rule out the client as the actual cause of a 401 Unauthorized Error. While it's probably not the HTML or CSS, it could be that the client may be sending a request that doesn't contain any authentication information.
Even though the 401 Unauthorized Error is a client error response, it doesn't mean we can rule out the server as the culprit. The server is still the network object producing the 401 Unauthorized Error and returning it as the HTTP response code to the client.
We'll go over all this in detail in the following sections.
Start With a Thorough Application Backup
Before attempting any changes to the system, make sure to perform a full backup of your application, database, etc. If you can, create a complete copy of the application onto a secondary staging server. This will give you a clean testing ground to test all potential fixes without threatening the sanctity of your live application.
Diagnosing a 401 Unauthorized Error
As discussed in the introduction, a 401 Unauthorized Error indicates that the client (the web browser, in most cases) has requested a restricted resource (such as a web page) from the server. Still, the client has failed to provide valid authentication credentials.
A 401 Error might occur in one of a handful of possible scenarios:
- The client sent its authentication credentials to the server, but the server rejected the credentials.
- The client failed to provide any authentication credentials within the request.
- The client is banned. Some applications use 401 Unauthorized Errors to restrict access requests from specific IP addresses.
Troubleshooting on the Client-Side
Since the 401 Unauthorized Error is a client error response code, it’s best to start by troubleshooting potential client-side issues.
Here are a handful of tips to try on the browser or device giving you problems.
Check the Requested URL
The most common cause of a 401 Unauthorized Error is an incorrect URL. As discussed before, web servers will disallow access to improper URLs. This could be anything from trying to access a file directory via a URL to gaining access to a private page meant for other users.
Double-check the exact URL returning the 401 error to ensure that it is the actual resource you intend to request.
Clear Relevant Cookies
HTTP cookies are tiny pieces of data stored on your local device. Websites and applications then use cookies to "remember" information about this particular browser and/or device.
Most modern web apps use cookies to store user authentication status. These cookies inform the web application which user is currently active and what kind of authorization to give the current client (browser). When a 401 Unauthorized Error occurs, the problem could be invalid or corrupted cookies, causing improper authentication for the server.
You only need to worry about cookies relevant to the website or application causing the problem in most cases. Cookies are stored based on the location of the domain, meaning you can remove only cookies that match the website domain (e.g., airbrake.io).
However, if you're not experienced with manually removing certain cookies, it's easier to clear all cookies at once.
Here are a few how-to articles to clear cookies depending on your browser:
Clear the Cache
Like cookies, local browser caches can cause 401 Unauthorized Error to appear. A cache is a collection of storage that retains local copies of web content on your device for later use. A browser's cache typically stores compressed snapshots of webpages you frequently visit, including images and other binary data your browser often accesses.
With a local copy of these resources on your device, your browser doesn't need to spend the time or bandwidth to download identical data every time you return to the same page.
For example, every time you open up Facebook, your page downloads content from the cache on your local device.
Since your browser's cache stores local copies of web content and resources, it's possible that a change to the live version of your application is conflicting with the cached version already on your device, causing a 401 Unauthorized Error.
Try clearing your browser's cache to see if that fixes the issue. As with cookies, clearing the cache is browser-dependent. Here are a few links to that relevant documentation for the most popular browsers:
Log Out and Log In
Since the application in question likely contains some form of authentication, the last client-side step to try is to log out and then log back in.
Clearing browser cookies will usually log you out automatically the next time you load the page. So, all you need to do is log back in.
In some situations, the application may be running into a problem with your previous session, which is a string that the server sends to the client to identify that client during future requests.
Your device stores session tokens (session strings) via cookies. The client then transfers these tokens to the server during a request. The problem is if the server doesn't recognize the session token sent by the client or the token is invalid. This will result in a 401 error.
For most web applications, logging out and logging back in will force the local session token to be recreated.
Debugging Common Platforms
Common software packages and content management systems (CMS) can also be responsible for the 401 Unauthorized Error. If you’re seeing this error, take a look at the stability and functionality of these platforms.
The most common content management systems — like WordPress, Joomla!, and Drupal — are all typically well-tested. Still, once you start making modifications to the underlying extensions or PHP code (the language in which nearly all modern content management systems are written), it’s too easy to cause an unforeseen issue resulting in a 401 error.
Here are a few tips to help you troubleshoot some of these popular software platforms.
Rollback Recent Upgrades
If you recently updated your CMS and now you’re seeing a 401 error, consider rolling back to the previous version on your CMS.
Similarly, any extensions or modules you may have recently upgraded can also cause server-side issues. If you believe this is why you’re seeing an error, revert to your previous CRM version.
However, certain CMSs don’t provide a version downgrade capability in some cases. This indicates that the base application, along with each new version released, is stable and bug-free. You’ll typically see this with more popular platforms.
Uninstall New Extensions, Modules, or Plugins
Extensions, modules, or plugins serve the same purpose across every system. They improve the capabilities and features of your CMS.
But you should be cautious with extensions because they can take full control of the system and make virtually any changes to the PHP code, HTML, CSS, JavaScript, or database. As such, uninstall any new extensions that you added before the 401 error.
Check for Unexpected Database Changes
It’s worth noting that if you uninstall an extension through the CMS dashboard, this doesn’t guarantee that changes made by the extension will fully revert. This is particularly true for WordPress extensions that have been given carte blanche within the application. This often includes full access rights to the database.
There are scenarios where an extension may modify database records that don’t “belong” to the extension itself. The extension may not know how to revert alterations to database records in those scenarios, even if you uninstall it.
If you’re reasonably convinced an extension is a likely culprit for the status code 401 error, open the database and manually look through tables and records likely modified by the extension.
Troubleshooting on the Server-Side
If you aren’t running a CMS application or you’re confident the 401 Unauthorized Error isn’t related to your CSM — here are some additional tips to help you troubleshoot what might be causing the issue on the server-side.
Confirm the WWW-Authenticate Header
RFC 7235 is the official standards document outlining how Hypertext Transfer Protocol (HTTP:/1.1): Authentication should be performed on the web. This is just one of the thousands of documents published by the Internet Engineering Task Force, an open community dedicated to creating open Internet standards.
According to the RFC 7235, a 401 Unauthorized Error response code sent by a server must also include the WWW-Authenticate response header, which contains one or more challenges. Each challenge is a string indicating how proper authentication can be obtained to access the requested resource.
The syntax of a WWW-Authenticate header is: WWW-Authenticate: <type> realm=<realm>. The <type> value can be one of several valid authentication schemes. <realm> describes the area or “realm” that can be accessed.
For example, a WWW-Authenticateheader of WWW-Authenticate: Basic realm="Access to the production server" indicates to the client that authentication requests should be Basic (an id and password credential combination). This will give access to the “production server.”
With this knowledge in hand, you can attempt to diagnose the 401 Unauthorized Error you’re seeing on your application by confirming that the application is sending a valid WWW-Authenticate response header. This header can give you extra information that may lead to a solution, such as showing which particular authentication schemes are expected by the server.
You can view HTTP headers either from the server or the client web browser. View headers in Google Chrome by pressing F12 to open the developer console, select the Network tab, then load or reload the specific page/resource showing the 401 Error. This will show the list of all resources involved in the transaction, including everything from the actual document to individual images.
Sort the results by the Status by clicking the Status table header, then find the “401” status code. Select that entry in the list, and you should be able to view the Headers tab for that request. Look under Response Headers for the associated WWW-Authenticate header.
Check Your Web Server Configuration
Most modern web servers provide one or more configuration files that allow you to easily adjust the server behavior based on a wide range of circumstances. For example, the server may reject requests to certain directories or URLs, resulting in a 401 Unauthorized Error.
Configuration options for each type of web server can vary dramatically. Here’s a list of a few popular servers:
Look Through the Logs
Nearly every web application will keep some form of server-side logs. Application logs are the history of what the application did. The log will show requested pages, connected servers, database results, etc. Server logs are related to the actual hardware running the application and will often provide details about the health and status of all connected services or even just the server itself. Google “logs [PLATFORM_NAME]” if you’re using a CMS, or “logs [PROGRAMMING_LANGUAGE]” and “logs [OPERATING_SYSTEM]” if you’re running a custom application, to get more information on finding the logs in question.
Debug Your Application Code or Scripts
Finally, if all else fails, it may be that a problem in some custom code within your application is causing the issue. Try to diagnose where the issue may be coming from by manually debugging your application and parsing through application and server logs.
Ideally, make a copy of the entire application to a local development machine and perform a step-by-step debug process, allowing you to recreate the exact scenario where the 401 Unauthorized Error occurred.
No matter the cause — and even if you managed to fix it this time — the appearance of an issue like the 401 Unauthorized Error within your own application is a good indication you may want to implement an error management tool. Error monitoring will help you automatically detect errors and report them to you when they occur. Here’s another blog you can read to learn more about error monitoring vs. logging.
Airbrake’s error monitoring software provides real-time error monitoring and automatic exception reporting for all your development projects. Airbrake’s state-of-the-art web dashboard ensures you receive round-the-clock status updates on your application’s health and error rates. Plus, Airbrake makes it easy to customize exception parameters, so you only gather the errors that matter most.
Check out Airbrake’s error monitoring software today and see why so many of the world’s best engineering teams use Airbrake!
Note: We published this post in November 2017 and recently updated it in May 2022.
