ARTIFACTORY: Troubleshooting Gradle/Maven Build Timeouts

Introduction 

When running Gradle or Maven builds that download dependencies from JFrog Artifactory, the build may fail during the dependency resolution or download phase with an error message similar to:

java.net.SocketTimeoutException: Read timed out

This indicates that the build tool stopped waiting for data from Artifactory because a timeout limit was reached on the client side.

This article will explain how to identify and resolve SocketTimeoutException: Read timed out errors in your Gradle and Maven builds by correctly configuring the client-side socket timeout properties when connecting to JFrog Artifactory.

Cause

This error occurs because the HTTP/HTTPS client used by Gradle or Maven did not receive data from the Artifactory server within its configured socket read timeout period. The connection is forcefully closed by the client, leading to the exception.

The default read timeout value configured in the build tool or its underlying HTTP client (e.g., potentially 30 seconds or 60 seconds) may be insufficient under certain conditions, such as:

• Network latency or instability between the build agent and Artifactory.
  
• Downloading very large artifacts.
  
• Slow response times from the Artifactory server (e.g., during high load, complex retrievals, or slow storage).
  

 

Diagnosis

You can often confirm the configured timeout value by enabling debug logging for your build tool:

• Gradle: Run with -d or --debug. Look for log lines from the HTTP client library indicating the timeout setting, for example:
  

  [DEBUG] [org.apache.http.impl.conn.DefaultManagedHttpClientConnection] ... set socket timeout to 30000

  
  
• (This example shows a 30,000 ms / 30-second timeout)
  
• Maven: Run with -X. The specific logs depend on the HTTP transport being used, but timeout values might be logged during connection setup.
  
  

Resolution

To overcome the socket timeout error, the timeout value of the build tool should be increased.

For Gradle:

Gradle uses system properties to control HTTP/HTTPS timeouts.

Method 1: Using gradle.properties (Recommended for persistence)

1. Locate your gradle.properties file. This can be in your project's root directory or in the Gradle User Home directory (~/.gradle/).
   

2. Add or modify the following lines, setting the timeout value in milliseconds. We recommend starting with 180000 (3 minutes) or 300000 (5 minutes):
   
    Properties

   # Set HTTP/HTTPS read timeout to 3 minutes (180000 ms)
   systemProp.http.socketTimeout=180000
   systemProp.https.socketTimeout=180000

Method 2: Using Command Line Arguments

1. Pass the properties directly when invoking Gradle:
   Bash

   gradle build -Dhttp.socketTimeout=180000 -Dhttps.socketTimeout=180000

    

For Maven:

Maven uses standard Java networking properties, which can be set via JVM options.

Method 1: Using MAVEN_OPTS Environment Variable

1. Set the MAVEN_OPTS environment variable before running Maven. Add the sun.net.client.defaultReadTimeout property (value in milliseconds):
   Bash

   # Linux/macOS Example (add to existing MAVEN_OPTS if any)
   export MAVEN_OPTS="$MAVEN_OPTS -Dsun.net.client.defaultReadTimeout=180000"
   
   # Windows Example (add to existing MAVEN_OPTS if any)
   set MAVEN_OPTS=%MAVEN_OPTS% -Dsun.net.client.defaultReadTimeout=180000
   
   # Then run Maven
   mvn install
   

 

Method 2: Using .mvn/jvm.config File (Maven 3.3+)

1. In the root directory of your project, create a directory named .mvn.
   

2. Inside the .mvn directory, create or edit a file named jvm.config.
   

3. Add the timeout property on a new line:

   -Dsun.net.client.defaultReadTimeout=180000

   
   

On Maven Transports: Some specific Maven HTTP transport implementations (Wagon providers) might have their own timeout settings configurable within your settings.xml. If the JVM options above do not seem to affect the timeout, consult the documentation for the specific transport provider you are using.

Choosing a Timeout Value:

• Start with a reasonable increase, such as 180000 (3 minutes) or 300000 (5 minutes).
  
• Monitor your builds. If timeouts persist, you might need a higher value.
  
• Avoid setting excessively high values (e.g., 30 minutes), as this can mask underlying network or server performance issues and cause builds to hang for long periods before failing.
  
  

In summary, SocketTimeoutException: Read timed out errors in Gradle and Maven builds downloading from Artifactory can be observed due to insufficient client-side timeouts. Increasing the appropriate timeout settings for your build tool, as outlined in this article, is the most common solution.