Troubleshooting — The Factory Problem Desk

Everyone eventually sees a confusing Jenkins error. This is the Problem Desk: what the message means, why it happened, and how to get out.

1 · "Pipeline syntax error" in Jenkinsfile

Problem

Jenkins rejects the Jenkinsfile with a syntax error.

Cause: The Jenkinsfile has a Groovy syntax mistake — missing brackets, wrong indentation, or a reserved word used incorrectly.

Fix:

Validate locally

# Use the Jenkins Pipeline Linter
cat Jenkinsfile | curl -X POST -u admin:password \
  --data-urlencode "jenkinsfile@-" \
  http://localhost:8080/pipeline-model-converter/validate

Common fix — matching braces

// Bad: missing closing brace
stages {
    stage('Build') {
        steps {
            echo 'hello'
// missing closing braces

// Good: all braces match
stages {
    stage('Build') {
        steps {
            echo 'hello'
        }
    }
}

Remember

Groovy is sensitive about braces and quotes. Every opening { needs a closing }. Every opening ( needs a closing ).

2 · "docker: command not found"

Problem

Pipeline fails with "docker: command not found" when trying to build an image.

Cause: The Jenkins agent doesn't have Docker installed, or the agent directive doesn't provide Docker.

Fix:

Option A — use a Docker agent

pipeline {
    agent {
        docker { image 'docker:24' }
    }
    // ... docker commands work here
}

Option B — install Docker on the agent

// On the Jenkins agent:
sudo apt-get install -y docker.io
sudo usermod -aG docker jenkins

Remember

Docker-in-Docker requires either Docker installed on the agent or a Docker agent with the Docker socket mounted.

3 · "No such credentials" or "credentials not found"

Problem

withCredentials fails with "no such credentials."

Cause: The credential ID doesn't match what's stored in Jenkins, or the credential type is wrong.

Fix:

Check available credentials

# In Jenkins UI: Manage Jenkins → Credentials → look at the ID

Make sure the ID matches exactly

withCredentials([usernamePassword(
    credentialsId: 'dockerhub',   // Must match exactly (case-sensitive)
    usernameVariable: 'USER',
    passwordVariable: 'PASS'
)])

Remember

Credential IDs are case-sensitive. DockerHub ≠ dockerhub. Check the exact ID in Jenkins UI.

4 · Build stuck in queue

Problem

The build shows "Waiting for next available executor" and never starts.

Cause: No agents are available, or all agents are busy with other builds.

Fix:

Check available agents

# Jenkins UI → Manage Jenkins → Nodes

Option A — use 'agent any'

pipeline {
    agent any   // Run on any available agent
}

Option B — add more agents

# In Jenkins UI: Manage Jenkins → Nodes → New Node

Remember

agent any uses whatever is available. If all agents are busy, the build waits. Add more agents or use Docker agents for burst capacity.

5 · "npm: not found" in Docker agent

Problem

Pipeline runs inside a Docker agent but npm or node isn't available.

Cause: The Docker image doesn't include the tools you need.

Fix:

Use the right image

agent {
    docker { image 'node:20-alpine' }   // Has node and npm
}

Or install tools in the pipeline

steps {
    sh 'apk add --no-cache npm'
}

Remember

Choose your Docker image based on the tools your pipeline needs. node:20-alpine for Node.js, python:3.12 for Python, maven:3.9 for Java.

6 · Pipeline fails on Windows agent

Problem

sh commands fail on a Windows agent.

Cause: sh is a Unix shell command. Windows uses bat or powershell.

Fix:

Use bat for Windows

steps {
    bat 'dir'
    bat 'npm install'
}

Or use a cross-platform approach

steps {
    sh 'echo "Running on Linux/Mac"'
}

Remember

Use sh for Linux/Mac agents, bat for Windows agents. If you need cross-platform, use a Docker agent with Linux.

7 · "Branch not found" in Multi-Branch Pipeline

Problem

Multi-Branch Pipeline doesn't detect a new branch.

Cause: Jenkins hasn't scanned the repo since the branch was created, or the branch doesn't have a Jenkinsfile.

Fix:

Trigger a scan

# Jenkins UI → Your Multibranch job → Scan Multibranch Pipeline Now

Make sure the branch has a Jenkinsfile

// The branch must have a Jenkinsfile at the repo root

Remember

Jenkins scans for branches periodically. If you need it immediately, trigger a manual scan. Every branch with a Jenkinsfile gets its own pipeline.