Fix Docker Login Failures in Jenkins CI Pipelines (2026)

The Jenkins agent is failing to authenticate with your Docker registry because the credentials it’s trying to use are either missing, invalid, or not properly configured for the agent’s environment.

Missing or Incorrect Docker Credentials in Jenkins Credentials Store:
- Diagnosis: Navigate to Manage Jenkins -> Credentials -> System -> Global credentials (unrestricted). Look for a credential of type "Username with password" that corresponds to your Docker registry username. Verify the username and password are correct.
- Fix: If missing, add a new credential: Type: Username with password, Username: <your_docker_registry_username>, Password: <your_docker_registry_password>, ID: docker-credentials (or a descriptive ID you’ll use in your pipeline). If incorrect, edit the existing credential.
- Why it works: Jenkins stores sensitive information like registry credentials here. Pipelines reference these by ID, and the plugin uses them to authenticate.
Incorrect Credential ID Used in Jenkins Pipeline:
- Diagnosis: Review your Jenkinsfile (or Freestyle job configuration). Find the stage or step where you’re attempting to log in to Docker. It will likely involve a withCredentials block or a specific Docker plugin step. Ensure the id parameter matches the ID you assigned in the Jenkins credentials store (e.g., id: 'docker-credentials').
- Fix: Update the id in your pipeline script to match the credential ID in Jenkins. For example, if your credential ID is my-docker-reg-creds, change withCredentials([usernamePassword(credentialsId: 'docker-credentials', ...)]) to withCredentials([usernamePassword(credentialsId: 'my-docker-reg-creds', ...)]).
- Why it works: The pipeline needs to explicitly tell Jenkins which set of credentials to use for the Docker login operation. Mismatching IDs mean Jenkins can’t find the correct credentials.
Docker Agent Not Running or Not Accessible:
- Diagnosis: If your Jenkins agent is a separate Docker container or a host where Docker is installed, ensure the Docker daemon is running and accessible. On Linux, check with sudo systemctl status docker. On Windows, check the Docker Desktop application. Also, verify the Jenkins agent user has permission to interact with the Docker socket (/var/run/docker.sock). You can test this by running docker ps as the Jenkins user.
- Fix: Start the Docker daemon if it’s stopped. If permissions are an issue, add the Jenkins user to the docker group: sudo usermod -aG docker $USER (replace $USER with the actual Jenkins user if different) and restart the agent process or log out/in.
- Why it works: The docker login command (or the underlying API calls made by Jenkins plugins) needs to communicate with the Docker daemon to store the credentials and authenticate.
Using docker.withRegistry Incorrectly (Declarative Pipeline):
- Diagnosis: In Declarative Pipelines, the docker.withRegistry directive is the standard way to handle authentication. Ensure you’re using the correct syntax and passing the credentialsId and url parameters properly. A common mistake is omitting the url for private registries or using the wrong one.
- Fix: Structure your pipeline stage like this:
```
stage('Build and Push') {
    agent any
    steps {
        script {
            docker.withRegistry('https://your.private.registry.com', 'docker-credentials') {
                // Your docker build and push commands here
                docker.build("my-image:latest").push()
            }
        }
    }
}
```
  Ensure https://your.private.registry.com is the correct registry URL and docker-credentials is the ID from Jenkins.
- Why it works: This block wraps your Docker commands, automatically performing the docker login before execution and docker logout afterward, using the specified credentials for the given registry URL.
Docker Configuration File (~/.docker/config.json) Issues on Agent:
- Diagnosis: If your Jenkins agent is a persistent VM or a container that reuses configurations, the ~/.docker/config.json file might contain stale or incorrect authentication tokens, or be missing the auths section entirely. Check the contents of this file on the agent machine where the pipeline is executing.
- Fix: Delete or rename the ~/.docker/config.json file. The docker login command (or withRegistry) will recreate it correctly. Alternatively, manually edit the file to remove incorrect entries.
- Why it works: The Docker CLI and many tools use this file to store authentication tokens. Corrupted or outdated entries can lead to login failures even if the Jenkins credentials are correct.
Network Connectivity or Firewall Issues:
- Diagnosis: The Jenkins agent needs to be able to reach your Docker registry’s URL over the network. Use curl -v https://your.private.registry.com or ping your.private.registry.com from the Jenkins agent’s environment to test connectivity.
- Fix: Ensure that any firewalls (on the agent machine, network devices, or cloud security groups) allow outbound traffic to your Docker registry’s IP address and port (typically 443 for HTTPS).
- Why it works: Authentication involves a network request to the registry. If the agent can’t establish a connection, the login will fail regardless of credentials.
Incorrect Registry URL (e.g., Docker Hub vs. Private Registry):
- Diagnosis: Are you trying to log in to Docker Hub (docker.io) or a private registry? The docker login command and withRegistry directive require the correct hostname. For Docker Hub, you often don’t need to specify a URL if using the standard docker command, but it’s good practice to be explicit in pipelines. For private registries, the full URL (e.g., registry.gitlab.com, ghcr.io, your.company.com:5000) is mandatory.
- Fix: Ensure the URL provided in your pipeline’s withRegistry block or the target of your docker login command is accurate. For Docker Hub, you might use 'https://index.docker.io/v1/' or simply let the plugin default if it supports that. For private registries, use the exact hostname and port.
- Why it works: The authentication mechanism is specific to the registry server. Providing the wrong server address means the login attempt goes to the wrong place, failing authentication.

The next error you’ll likely encounter after fixing login issues is a permission denied error when trying to push an image, because the user specified in the credentials might not have the necessary repository permissions.

Common Causes and Fixes for Docker Login Failures in Jenkins