Troubleshooting Common Issues

1. Debugging Pipeline Failures

Issue	Description	Solution
Pipeline hangs or times out	Pipeline execution stops responding or exceeds timeout limits	Check logs for stuck stages, increase timeout settings in Jenkins configuration, or use `timeout` step to manage execution limits
Build fails with "No such file or directory"	Build process tries to access a file that does not exist	Verify file paths in scripts, ensure proper working directory setup, and use `ls` or `find` commands to validate file existence before use
Permission denied errors	Build fails due to insufficient permissions for files or directories	Ensure Jenkins user has appropriate read/write access to required resources, and check file permissions using `chmod` or `chown`
Plugin compatibility issues	Builds fail due to outdated or conflicting plugins	Update plugins via Jenkins UI or CLI, verify plugin versions are compatible with current Jenkins version

Example: Using Jenkins Pipeline Debugging Tools

pipeline {
    agent any
    stages {
        stage('Debug Example') {
            steps {
                script {
                    echo "Current working directory: ${pwd()}"
                    sh 'ls -la'
                    sh '''
                        echo "Debugging step"
                        env
                    '''
                }
            }
        }
    }
}

Note: Use echo and sh steps to inspect environment variables and file system state during pipeline execution.

Warning: Avoid using sh steps with sensitive data in logs; consider using withCredentials for secure handling.

Common Debugging Techniques

Use echo to print variable values and stage progress
Utilize sh steps to run shell commands and inspect environment
Check Jenkins logs for detailed error messages
Validate file paths and permissions before pipeline steps

2. Resolving Plugin Conflicts

Plugin	Conflicts With	Resolution	Status
Pipeline: Groovy Plugin	`Workflow Script for Job`	Use `pipeline { }` syntax consistently	DEPRECATED
Job Configuration Plugin	`Build Environment`	Use `buildEnvironment` instead of `environment`	NEW
Maven Integration Plugin	`Build Steps`	Ensure `maven` command is available in PATH	EXPERIMENTAL

Example: Resolving Plugin Conflict

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                sh 'mvn clean install'
            }
        }
    }
}

Note: Ensure all plugins are compatible with the Jenkins version.

Warning: Avoid mixing buildEnvironment and environment in the same job.

3. Fixing Memory Issues

Issue	Symptoms	Solution
Out of Memory Errors	`java.lang.OutOfMemoryError: Java heap space`	Adjust JVM heap size using `-Xmx` parameter in Jenkins startup script.
GC Overhead Limit Exceeded	Long GC times, frequent full GCs	Increase heap size or tune garbage collector settings (e.g., G1GC).

Example: Increasing Heap Size

JAVA_OPTS="-Xmx2g -Xms512m" java -jar jenkins.war

Note: Ensure sufficient RAM is available on the host machine to accommodate increased memory allocation.

Memory Management Best Practices

Monitor Jenkins memory usage regularly using JMX or plugins like Memory Monitor.
Use -XX:+UseG1GC for better garbage collection performance in large heaps.
Set -Xmx to no more than 50% of available system RAM to avoid swapping.

4. Resolving Agent Connection Issues

Issue	Description	Solution
Agent not connecting to Jenkins master	Agent fails to establish a connection with the Jenkins master server.	Check network connectivity, firewall settings, and ensure the agent is started with correct Jenkins URL and secret.
Connection timeout errors	Agents timeout while trying to connect to the master due to network delays or misconfiguration.	Verify Jenkins master URL, increase timeout settings in agent startup, and ensure no network interruptions.
Invalid agent secret or token	Incorrect or expired secret prevents the agent from authenticating with Jenkins.	Regenerate the agent secret from the Jenkins UI and reconfigure the agent with the new secret.
Jenkins master unreachable from agent	The agent cannot reach the Jenkins master due to DNS or IP misconfiguration.	Ensure that the Jenkins master's public URL is accessible from the agent machine and update DNS or hosts file if needed.

Example: Restarting an Agent

java -jar agent.jar -jnlpUrl https://jenkins.example.com/computer/agent1/slave-agent.jnlp -secret <secret>

Note: Ensure that the -jnlpUrl and -secret match exactly what is provided in the Jenkins UI under the agent configuration.

Warning: If the agent is running on a different network or behind a proxy, make sure that all required ports (e.g., 50000 for JNLP) are open and accessible.

5. Debugging SCM Checkout Failures

Issue	Description	Solution	Notes
SCM checkout timeout	Checkout process exceeds configured timeout limit	Adjust `scmCheckoutTimeout` in Jenkins global settings or job configuration	Default is 10 minutes. Increase if large repositories are being checked out
Permission denied to repository	Insufficient access rights to clone or pull from SCM	Verify credentials in Jenkins configuration and ensure user has read access to repo	Use SSH keys or personal access tokens for secure authentication
Branch not found	Specified branch does not exist in remote repository	Ensure correct branch name is used in job configuration or SCM settings	Check for typos in branch names or case sensitivity issues
Network connectivity issues	Unable to reach remote SCM server due to network problems	Check Jenkins server's network access to the SCM host; test with `ping` or `curl`	Firewall or proxy settings may block connection to SCM server
Git shallow clone issues	Shallow clones fail to fetch full history or submodules	Disable shallow clone in job configuration or set `git config --global core.longpaths true`	Useful for large repositories with many commits or submodules

Example: Configure SCM timeout in Jenkins Pipeline

pipeline {
    agent any
    stages {
        stage('Checkout') {
            steps {
                checkout([
                    $class: 'GitSCM',
                    branches: [[name: 'main']],
                    userRemoteConfigs: [[url: 'https://github.com/example/repo.git']],
                    scmCheckoutTimeout: 30
                ])
            }
        }
    }
}

Note: SCM checkout failures often stem from misconfigured credentials or network issues. Always verify the repository URL, branch name, and authentication before troubleshooting further.

6. Fixing Credential Access Errors

Issue	Solution	Notes
No credentials found	`credentials.xml` missing or corrupted	Check Jenkins home directory for `credentials.xml`
Invalid credential ID	Verify credential ID in configuration	Use `credentials.xml` to validate IDs
Permission denied	Assign proper user roles in Jenkins	Ensure `Manage Credentials` permission is granted

Example: Setting up credentials in Jenkins UI

Manage Jenkins > Manage Credentials > System > Global > Add Credentials

Note: Ensure that the Jenkins user has read access to credentials.xml.

Warning: Never store credentials in plain text files outside of Jenkins.

7. Resolving Build Queue Issues

Issue	Description	Solution
Build queue stuck	Builds remain in queue indefinitely without starting	Check if there are enough executors available. If all executors are busy, new builds wait in queue.
Builds not starting after queue	Builds are queued but never begin execution	Verify Jenkins is not in "quiet mode" or under maintenance. Check for resource constraints (CPU, memory).
High queue load	Too many builds queued, causing delays	Use the "Build Queue" view to identify bottlenecks. Consider increasing executors or optimizing build duration.

Example: Checking Executor Status

curl -u "admin:password" http://jenkins.example.com/computer/api/json

Example: Increasing Executors

{
  "executors": 4,
  "label": "build-node"
}

Note: Ensure that the nodes have sufficient resources (CPU, RAM) to handle additional builds.

Warning: Adding too many executors can lead to resource contention and slower overall performance.

8. Debugging Workspace Corruption

Issue	Description	Solution
Workspace files missing or corrupted	Build fails due to missing or corrupted files in the workspace directory.	Check disk space and file permissions. Rebuild the workspace or restore from backup.
Permission denied errors	Errors occur when Jenkins tries to read/write files in the workspace.	Ensure Jenkins user has proper permissions on workspace directory. Use `chmod` or `chown` to fix.
Concurrent access issues	Multiple builds or plugins attempt to modify workspace files simultaneously.	Use `lock` or `workspace` locks to prevent concurrent access. Configure build strategies accordingly.

Example: Checking workspace permissions

ls -ld /var/lib/jenkins/workspace/<job-name>

Example: Rebuilding workspace

rm -rf /var/lib/jenkins/workspace/<job-name>
jenkins-cli -s http://localhost:8080/ build <job-name>

Note: Regular backups of the Jenkins workspace are recommended to avoid data loss during corruption incidents.

Warning: Manual deletion of workspace directories should be done carefully to avoid breaking ongoing builds.

9. Fixing Webhook Delivery Issues

Issue	Description	Solution
Webhook not triggering builds	Builds are not triggered when a webhook is sent to Jenkins.	Verify the webhook URL in the source control system matches the one generated by Jenkins. Ensure the correct event type is configured (e.g., push, pull request). Check Jenkins logs for errors related to webhook processing.
Builds trigger but fail immediately	Builds start but fail with an error message.	Check the build logs for specific errors. Ensure that required environment variables or credentials are correctly configured in Jenkins. Validate the payload structure matches what Jenkins expects.
Webhook response timeout	Source control system reports a timeout when sending webhook.	Ensure Jenkins is accessible from the source control server. Check firewall and network settings. Consider increasing timeout values in Jenkins or using a reverse proxy like Nginx to handle long-running requests.

Example: Configure Webhook URL in GitHub

curl -X POST \
  -H "Authorization: token <GITHUB_TOKEN>" \
  -H "Content-Type: application/json" \
  https://api.github.com/repos/<ORG>/<REPO>/hooks \
  -d '{
    "name": "web",
    "active": true,
    "events": ["push", "pull_request"],
    "config": {
      "url": "http://jenkins.example.com/github-webhook/",
      "content_type": "json",
      "secret": "<WEBHOOK_SECRET>"
    }
  }'

Note: Ensure that the Jenkins server is accessible from the source control system and that any required authentication (e.g., tokens or secrets) is correctly configured.

10. Using Replay for Pipeline Debugging

Example: Replay a Pipeline Run

pipeline {
    agent any
    stages {
        stage('Debug') {
            steps {
                script {
                    // Replay the pipeline from a specific point
                    replayBuild("my-pipeline/123")
                }
            }
        }
    }
}

Property	Description	Values
replayBuild()	Replays a previous build of a pipeline	`String` - Build identifier (e.g., `"job/123"`)

Note: The replayBuild function is available in Jenkins Pipeline plugin version 2.20+.

Warning: Replaying builds may not reflect the current state of source code or environment if changes have been made since the original run.

11. Analyzing Thread Dumps

Thread State	Description	Indication
RUNNABLE	Thread is executing in the JVM	Active execution, no blocking
BLOCKED	Thread is waiting to acquire a monitor lock	Contention for shared resources
WAITING	Thread is waiting indefinitely for another thread to perform an action	Potential deadlock or long-running wait
TIMED_WAITING	Thread is waiting for a specified amount of time	Expected timeout behavior, e.g., sleep or wait with timeout
TERMINATED	Thread has completed execution	Completed task or error termination

Example: Extracting Thread Dump via JMX

import javax.management.MBeanServerConnection;
import javax.management.ObjectName;
import java.lang.management.ManagementFactory;

MBeanServerConnection connection = ManagementFactory.getPlatformMBeanServer();
ObjectName threadBeanName = new ObjectName("java.lang:type=Threading");
String[] threadIds = (String[]) connection.getAttribute(threadBeanName, "AllThreadIds");
String threadDump = (String) connection.invoke(threadBeanName, "getThreadInfo", new Object[]{threadIds}, new String[]{"[J"});
System.out.println(threadDump);

Note: Thread dumps can be generated using jstack command or via JMX MBeans in Jenkins.

Common Thread Dump Analysis Patterns

Deadlock Detection: Look for threads in BLOCKED state waiting on locks held by other threads.
High CPU Usage: Identify RUNNABLE threads with high execution time or stack traces involving intensive computation.
Resource Contention: Threads in BLOCKED or WAITING states indicate resource bottlenecks (e.g., database connections, file locks).