Job is failing because a parameter length exceeded

Issue

When using very large parameters in a given job, the builds fail throwing the following in the logs:

Caused by: hudson.plugins.git.GitException: Error performing git command: git $SOME_WORKSPACE_PATH
	at org.jenkinsci.plugins.gitclient.CliGitAPIImpl.launchCommandIn(CliGitAPIImpl.java:2748)
	at org.jenkinsci.plugins.gitclient.CliGitAPIImpl.launchCommandIn(CliGitAPIImpl.java:2662)
	at org.jenkinsci.plugins.gitclient.CliGitAPIImpl.launchCommandIn(CliGitAPIImpl.java:2658)
	at org.jenkinsci.plugins.gitclient.CliGitAPIImpl.launchCommand(CliGitAPIImpl.java:1981)
	at org.jenkinsci.plugins.gitclient.CliGitAPIImpl$5.execute(CliGitAPIImpl.java:1047)
	[...]
Caused by: java.io.IOException: Cannot run program "git" (in directory "$SOME_WORKSPACE_PATH"): error=7, Argument list too long▼

Environment

Explanation

This is an OS limitation, not a Jenkins limitation. On Linux systems, there are two independent limits:

ARG_MAX: The total size of all environment variables and arguments combined
MAX_ARG_STRLEN: The maximum size for each individual parameter

On Linux, ARG_MAX is typically 2 MB, but MAX_ARG_STRLEN limits each parameter to approximately 128 KB to 400 KB depending on the distribution. This means you can exceed MAX_ARG_STRLEN for a single large parameter even when well below the ARG_MAX total limit.

For more information, refer to:

Resolution

Passing large amounts of data as raw parameters is not a recommended practice. Instead, use files to store and retrieve data, as files do not face the same OS-imposed limitations.

Split parameters across multiple parameters

If you must use parameters, split large data across multiple smaller parameters to stay within the MAX_ARG_STRLEN limit for each parameter.

For example, instead of one parameter with 350 hostnames, use two parameters with 175 hostnames each.

This approach only delays the problem. You will eventually hit limits as data grows.

Use Config File Provider plugin

Use the Config File Provider plugin plugin to store data in managed configuration files.

Install the Config File Provider plugin plugin.
Navigate to Manage Jenkins Managed files.
Click Add a new Config.
Select JSON file or Custom file.
Enter the file content (e.g., list of hostnames in JSON format).
Note the generated File ID.

Use the file in your Pipeline:

configFileProvider([configFile(fileId: 'YOUR_FILE_ID', variable: 'HOSTNAMES_FILE')]) {
    sh 'cat $HOSTNAMES_FILE'
    // Process the file content
}▼

This approach requires manual intervention to update the file content for each build.

Store data in SCM

Store data files in your source control repository and retrieve them during the build.

Create a JSON or text file in your repository containing the data.
Commit and push the file.

Reference the file in your Pipeline:

def hostnamesFile = readFile('hostnames.json')
def hostnames = readJSON text: hostnamesFile
// Process the hostnames▼

This approach allows automated updates through version control.

Tested product/plugin versions

CloudBees CI on traditional platforms - client controller - 2.479.3.2
Config File Provider plugin - 980.v88956a_a_5d6a_d

This article is part of our Knowledge Base and is provided for guidance-based purposes only. The solutions or workarounds described here are not officially supported by CloudBees and may not be applicable in all environments. Use at your own discretion, and test changes in a safe environment before applying them to production systems.