1. Overview
In this tutorial, we’ll learn about the error “Return code is: 501, ReasonPhrase: HTTPS Required”. We’ll start by understanding what this error means, and then explore the steps to resolve it.
2. Maven Moving to HTTPS
Maven ensures the automatic download of external libraries from the Maven central repository. However, downloading over HTTP raises security concerns, such as the risk of man-in-the-middle (MITM) attacks. During this attack, malicious code may be injected during the build phase, which can infect the downstream components and their end-users.
To maintain data integrity and encryption, the Maven Central Repository from January 15, 2020, has stopped communication over HTTP. It means any attempts to access the central repository with HTTP will result in an error “Return code is: 501, ReasonPhrase: HTTPS Required”. To fix this, we need to ensure that dependencies are fetched using HTTPS instead of HTTP.
3. Update Maven Version
From Maven version 3.2.3, the central repository is, by default, accessed via HTTPS. If we’re using an older version of Maven, we can update the Maven version to 3.2.3 or later to fix the error.
To update the Maven version, we can download the latest stable build version from the official Apache Maven download page.
4. Restrict the Current Maven Version to Use HTTPS Links
Maven provides a settings file, settings.xml, which we can use to configure the Maven installation. This settings.xml file contains all the local and remote repositories links. To fix this error, we need to make sure that we’re using HTTPS in Maven settings. Here are the steps to verify and update the Maven settings:
4.1. Fix mirrors Section in settings.xml
If a <mirrors> section exists in the settings.xml file, we need to make sure the URL for the mirror is https://repo.maven.apache.org/maven2/. If the section doesn’t exist, we can add it like this:
<mirrors>
<mirror>
<id>central</id>
<url>https://repo.maven.apache.org/maven2/</url>
<mirrorOf>central</mirrorOf>
</mirror>
</mirrors>
4.2. Fix pluginRepositories Section in settings.xml
Similar to the mirrors section, we may also have a pluginRepositories section where we need to use the URL with HTTPS:
<pluginRepositories>
<pluginRepository>
<id>central</id>
<url>https://repo.maven.apache.org/maven2/</url>
</pluginRepository>
</pluginRepositories>
4.3. Fix repositories Section in pom.xml
The pom.xml file also contains a repository section where we need to use the URL with HTTPS:
<repositories>
<repository>
<id>central</id>
<name>Central Repository</name>
<url>https://repo.maven.apache.org/maven2</url>
<layout>default</layout>
<snapshots>
<enabled>false</enabled>
</snapshots>
</repository>
</repositories>
After making these changes, Maven should download the dependencies over HTTPS.
5. Fix When the Build Environment Doesn’t Support HTTPS
Sometimes, we may face technical constraints, such as using JDK6 in the build environments or lacking HTTPS support. These limitations can impede our transition to HTTPS.
To support such scenarios, the Maven team has established a dedicated domain for insecure traffic. We can replace all the existing references with this URL to facilitate downloads over HTTP.
6. Conclusion
In this tutorial, we explored the different ways to resolve the “Return code is: 501, ReasonPhrase: HTTPS Required” error. First, we explored the basic details of the error.
Afterward, we looked at the fix by updating the Maven version or fixing the settings.xml file.
