Jenkins Troubleshooting

Every Jenkins user meets a red build, a stuck queue, or a server that refuses to start. Calm, methodical checks solve most of these cases in minutes. A good troubleshooter follows a fixed path from symptom to cause to fix instead of guessing.

The Layman's View

A doctor does not prescribe medicine on sight. The doctor asks about symptoms, runs tests, finds the cause, and then treats it. Jenkins problems respond to the same routine. Collect the symptom, read the evidence, locate the cause, and apply a fix.

The Five-Step Method

 1. WHAT FAILED?        job, stage, agent, or whole server
        |
        v
 2. READ THE LOG        console output and system log
        |
        v
 3. FIND THE FIRST ERROR  later errors often follow from it
        |
        v
 4. CHANGE ONE THING    test the fix
        |
        v
 5. RECORD THE RESULT   share the lesson with the team

Where the Evidence Lives

Source	Location	Shows
Console Output	Build page, left menu	Every command and its output
Pipeline Steps	Build page, Pipeline Steps	Result per step
System Log	Manage Jenkins, System Log	Server-level warnings and errors
Agent Log	Nodes, agent name, Log	Connection problems
Service Log	journalctl -u jenkins on Linux	Start-up failures

Problem: Build Fails With Command Not Found

Symptom

The console shows a message such as mvn: command not found or docker: not found.

Cause

The agent lacks the tool, or the job does not load it.

Fix

• Add the tools block or select the configured tool in the job.
• Install the program on the agent and confirm that its folder sits on the PATH.
• Print the PATH with sh 'echo $PATH' to see what the build sees.

Problem: Build Waits in the Queue

Symptom

The queue shows a message such as Waiting for next available executor or No agent matches label.

Cause

All executors are busy, the agent is offline, or the label in the job has no match.

Fix

• Open Manage Jenkins, then Nodes, and confirm that agents show online.
• Compare the label in the Jenkinsfile with the labels on the agents.
• Add executors or agents when demand exceeds capacity.

Problem: Git Checkout Fails

Symptom

The log shows Authentication failed or Repository not found.

Cause

The credential is wrong, expired, or lacks access to the repository.

Fix

• Open the credential and update the password or token.
• Run git ls-remote with the same URL on the agent to test access.
• Confirm the repository address and branch name.

Problem: Permission Denied on Files

Symptom

Scripts stop with Permission denied.

Cause

The script lacks the execute bit, or the Jenkins user cannot write to a folder.

Fix

chmod +x deploy.sh
git update-index --chmod=+x deploy.sh

The second command stores the executable flag in Git, so every checkout keeps it.

Problem: Out of Memory or Disk Space

Symptom

Builds crash with OutOfMemoryError, or Jenkins reports low disk space on a node.

Fix

• Raise the Java heap through the JAVA_OPTS setting, for example -Xmx2g.
• Enable Discard old builds to trim history.
• Clean workspaces with the cleanWs step in the post block.
• Prune unused Docker images on agents.

Problem: Jenkins Will Not Start

Symptom

The service stops right after launch or the web page does not load.

Checks

1. Read the service log with journalctl -u jenkins -n 100.
2. Confirm that Java is installed and that its version matches the Jenkins requirement.
3. Check whether another program already uses port 8080.
4. Look at free disk space on the Jenkins home folder.
5. Disable the most recently installed plugin by moving its file out of the plugins folder.

Problem: Plugin Conflicts After an Upgrade

A plugin update can break another plugin that depends on it. Open Manage Jenkins and Plugins and read the warnings at the top of the page. Roll back by installing the previous version from the plugin archive or by restoring a backup. Test upgrades on a staging server before production.

Problem: Pipeline Syntax Errors

Symptom

The run stops at once with a message such as WorkflowScript: expected a step.

Fix

• Open the line number from the message and check braces and quotes.
• Use the Pipeline Syntax snippet generator at the bottom of the job page.
• Run the Declarative Linter from the command line or the editor plugin.

Prevention Habits

• Keep a staging Jenkins for testing upgrades.
• Back up the Jenkins home folder on a schedule.
• Store jobs as Jenkinsfiles in Git.
• Set alerts on disk usage and agent status.
• Write short run books for the five problems your team meets most often.

Each solved problem adds a note to your run book, and over time the red builds shrink in number and in drama.