503 Service Unavailable Error: What It Is and How to Fix It

A 503 Service Unavailable Error is an HTTP response status code indicating that a server is temporarily unable to handle the request. This may be due to the server being overloaded or down for maintenance. This particular response code differs from a code like the 500 Internal Server Error we explored some time ago. While a 500 Internal Server Error indicates an issue preventing the server from handling the request entirely, a 503 Service Unavailable Error is an indication that the server is still functioning properly, since it’s able to process the request and has opted to return the 503 response code.

As with most HTTP response codes that indicate an error like this, it can be difficult to determine the exact cause of a 503 Service Unavailable. There are dozens of possible HTTP status codes used to represent the complex relationship between the client, a web application, a web server, and often multiple third-party web services, so determining the cause of a particular status code can be a challenge, even under the best of circumstances. In this article we’ll examine the 503 Service Unavailable by looking at a few troubleshooting tips, along with some potential fixes for common problems that might be causing this issue, so let’s get started!

The Problem is Server-Side

All HTTP response status codes that are in the 5xx category are considered server error responses. Unlike the 502 Bad Gateway Error we’ve looked at recently, which indicates that a server somewhere in the connection chain is down or unavailable, a 503 Service Unavailable Error simply indicates that the server is temporarily unable to handle the request, but that is is functioning as normal otherwise. Unlike gateway related 5xx response codes that may indicate issues either on the web server or another server further upstream, the 503 Service Unavailable code generally indicates an issue on the actual web server hosting your application.

In most cases, the web server should provide a user-friendly page indicating that the service is temporarily unavailable. Additionally, the application should send a Response-After HTTP header, which informs the user agent (client) how long it should wait to attempt the request once again. This value should either be a Date value indicating the timestamp the service will be available, or a numeric value indicating how many seconds from now the user agent must wait to retry.

Since the 503 Service Unavailable indicates that something has gone wrong within the server of your application, we can largely disregard the client side of things. If you’re trying to diagnose an issue with your own application, you can immediately ignore most client-side code and components, such as HTML, cascading style sheets (CSS), client-side JavaScript, and so forth. This doesn’t apply solely to web sites, either. Many smart phone apps that have a modern looking user interface are actually powered by a normal web application behind the scenes; one that is simply hidden from the user. If you’re using such an application and a 503 Service Unavailable Error occurs, the issue isn’t going to be related to the app installed on your phone or local testing device. Instead, it will be something on the server-side, which is performing most of the logic and processing behind the scenes, outside the purview of the local interface presented to the user.

Start With a Thorough Application Backup

As with anything, it’s better to have played it safe at the start than to screw something up and come to regret it later on down the road. As such, it is critical that you perform a full backup of your application, database, and so forth, before attempting any fixes or changes to the system. Even better, if you have the capability, create a complete copy of the application onto a secondary staging server that isn’t “live,” or isn’t otherwise active and available to the public. This will give you a clean testing ground with which to test all potential fixes to resolve the issue, without threatening the security or sanctity of your live application.

Diagnosing a 503 Service Unavailable Error

As mentioned, a 503 Service Unavailable Error indicates that the server (typically the actual web server on which your application is running) is temporarily unavailable. This is usually due to the server being “down” for scheduled maintenance, or due to a heavy load of traffic that is preventing it from properly serving all incoming requests. In the case of the former, the server has not actually crashed or shut down but has, instead, set itself to a mode of service that prevents most requests from behaving as normal. Thus, attempting to access a normally-functional page now displays a 503 Service Unavailable Error, ideally doing so alongside a message about the server being down for maintenance. In this mode, the server is still up and running, but only administrators will have access to it, whereas normal public requests will be turned away until maintenance is complete.

In the other scenario where the server is rejecting the request due to overload, this usually means there is an unexpected onslaught of traffic/incoming requests. In order to maintain some semblance of normal behavior for a portion of the requests, the server has effectively throttled itself by rejecting a portion of all incoming requests and returning a 503 Service Unavailable Error. If the application/server was configured correctly, the request can usually be completed by waiting a little while and retrying a few times, hopefully enough for the traffic spike to die down and let you in.

That said, if your application is responding with 503 Service Unavailable codes and the server should not be performing any kind of maintenance that would explain the situation, this is an issue that many other visitors could be experiencing as well, dramatically hindering your application’s ability to service users. We’ll go over some troubleshooting tips and tricks to help you try to resolve this issue. If nothing here works, don’t forget that Google is your friend. Don’t be afraid to search for specific terms related to your issue, such as the name of your application’s CMS or web server software, along with 503 Service Unavailable Error. Chances are you’ll find others who have experienced this issue and have been given a solution.

Troubleshooting on the Server-Side

Here are some additional tips to help you troubleshoot what might be causing the 503 Service Unavailable to appear on the server-side of things:

• Reboot the Server – If you or an administrator have the ability to do so, one of the simplest solutions is often to restart the web server hosting the application. If your application is spread over multiple servers, make sure all are rebooted in the proper manner so the system is brought back online as normal. A 503 Service Unavailable code could be a result of a bottleneck somewhere in the server chain that hosts your application, so a simple reboot could refresh everything and get you back up and running.

• Check for Unexpected Maintenance – You may not realize it, but your server and/or application may be configured to go down for maintenance automatically. Many modern content management systems like WordPress will automatically download and install updates to their base software without any intervention on your behalf. The web server could be issuing 503 Service Unavailable Errors during this period, particularly if your application resides on a slower server or a shared host. If you’re able to access the administration settings of your application/server, check the configuration options for automatic maintenance scheduling or the like, disabling such options if you’d rather have direct control over that process (just don’t forget to upgrade to newer versions fairly regularly, as they typically include critical security fixes).

• Server Connectivity Issues – While it may sound simple, it’s entirely possible that a 503 Service Unavailable Error simply indicates that a server somewhere in the chain is down or unreachable for whatever reason. Most modern applications don’t reside on a single server, but may, instead, be spread over multiple systems, or even rely on many third-party services to function. If any one of these servers are down for maintenance or otherwise inaccessible, this could result in an error that appears to be from your own application.

• Improper Firewall Configuration – A firewall is a basic security device that monitors network traffic and acts as a gatekeeper, deciding which traffic is safe and which could be malicious. In most cases, all potentially harmful traffic is stopped (and may be logged for network admin use). In some situations, it’s entirely possible for a firewall configured somewhere on the network in which your application is running to be preventing some form of critical traffic from getting through. This is particularly true for applications that rely on content delivery networks (CDNs), which act as a third-party host for “heavy” content like images or videos, hosting that content on behalf of your application, so your application can maintain its speed and efficiency. However, automatic firewall services can sometimes perform false positives, mistaking perfectly safe and valid content from CDNs or elsewhere as malicious, thereby shutting off that stream of content in an instant, which could lead to a 503 Service Unavailable Error.

• Check the Logs – Nearly every web application will keep some form of server-side logs. Application logs are typically the history of what the application did, such as which pages were requested, which servers it connected to, which database results it provides, and so forth. Server logs are related to the actual hardware that is 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.

• Application Code or Script Bugs – 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 through manually debugging your application, along with 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, which will allow you to recreate the exact scenario in which the 503 Service Unavailable Error occurred and view the application code at the moment something goes wrong.

No matter what the cause, the appearance of a 503 Service Unavailable Error within your own web application is a strong indication that you may need an error management tool to help you automatically detect such errors in the future. The best of these tools can even alert you and your team immediately when an error occurs. 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. No matter what you’re working on, Airbrake easily integrates with all the most popular languages and frameworks. Plus, Airbrake makes it easy to customize exception parameters, while giving you complete control of the active error filter system, so you only gather the errors that matter most.