> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://support.stacktrack.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Jenkins Pipeline Troubleshooting

A Practical Guide for Debugging Jenkins Pipelines (With Examples)

### Why Jenkins Pipeline Troubleshooting Is Critical
Jenkins pipelines are the backbone of modern CI/CD. But as pipelines grow:
* Failures become harder to diagnose
* Logs become noisy
* Small syntax mistakes block entire delivery pipelines to production
The below described steps focuses on real Jenkins pipeline problems, why they happen, and how to fix them using proven patterns.

## Understanding Exit Codes in Jenkins Pipelines
By default, Jenkins fails the entire build if any shell command returns a non-zero exit code.
This is problematic when you want to:
* Treat warnings differently from failures
* Continue execution after recoverable errors
* Log issues without failing the build
* Handle specific exit codes intelligently
### Solution
```
Capture Exit Codes Explicitly

Use returnStatus: true to take control.

pipeline {
    agent any
    stages {
        stage('Run Script') {
            steps {
                script {
                    def exitCode = sh(
                        script: 'command',
                        returnStatus: true
                    )

                    if (exitCode == 2) {
                        echo "⚠️ Warning condition detected"
                    } else if (exitCode != 0) {
                        echo "❌ Command failed with exit code ${exitCode}"
                    } else {
                        echo "✅ Command executed successfully"
                    }
                }
            }
        }
    }
}

```
### Best Practices
* Document exit code meanings
* Use for scripts with controlled failure logic
* Avoid brittle pipelines that fail unnecessarily
## Debugging Jenkins Pipeline Syntax Errors
Groovy syntax errors appear only at runtime, after:
* Committing code
* Pushing to Git
* Triggering a Jenkins build
* Common frustrations:
* Missing braces {}
* Invalid Declarative syntax
* Cryptic stack traces
* Endless commit → fail → fix cycles
### The Solution: Lint Before You Commit
```
Step 1: Install Groovy Linter
npm install -g npm-groovy-lint

Step 2: Lint Jenkinsfile Locally
npm-groovy-lint -p Jenkinsfile
npm-groovy-lint -p Jenkinsfile --fix

Step 3: Add a Git Pre-Commit Hook
#!/bin/sh
npm-groovy-lint -p Jenkinsfile --failon error
if [ $? -ne 0 ]; then
    echo "❌ Jenkinsfile has syntax errors."
    exit 1
fi

Common Jenkinsfile Syntax Errors
// ❌ Missing closing brace
stage('Build') {
    steps {
        sh 'make build'

// ✅ Correct
stage('Build') {
    steps {
        sh 'make build'
    }
}

// ❌ Invalid structure
stages {
    script {
        def x = 1
    }
}

// ✅ Correct structure
stages {
    stage('Process') {
        steps {
            script {
                def x = 1
            }
        }
    }
}

Validating Jenkinsfiles Without Running Builds
Jenkins CLI
java -jar jenkins-cli.jar -s <http://jenkins-url> declarative-linter < Jenkinsfile

Jenkins API
curl -X POST -F "jenkinsfile=<Jenkinsfile" \
<http://jenkins-url/pipeline-model-converter/validate>

```
## Pipelines From Hanging Forever
* Network calls that never return
* Stuck Docker containers
* SSH commands without limits
* Commands waiting for input
* Impact: Blocked agents, wasted resources, manual cleanup.
### The Solution: Layer Your Timeouts
```
Command-Level Timeout
timeout(time: 10, unit: 'MINUTES') {
    sh 'kubectl rollout status deployment/myapp'
}

Stage-Level Timeout
stage('Integration Tests') {
    options {
        timeout(time: 30, unit: 'MINUTES')
    }
    steps {
        sh './run-tests.sh'
    }
}

Pipeline-Level Timeout (Mandatory)
pipeline {
    agent any
    options {
        timeout(time: 2, unit: 'HOURS')
    }
    stages {
        // stages
    }
}

```
## Pipeline failures due to Workspace Issues and Cleanup
Builds fail due to:
* Leftover artifacts
* Corrupted workspaces
* Disk exhaustion
### Solution
```
Clean Workspace Safely
stage('Clean') {
    steps {
        cleanWs()
    }
}

Or skip checkout when not needed:

options {
    skipDefaultCheckout()
}

```
## Parallel Stage Failures (Hidden Errors)
When parallel stages fail:
* Jenkins reports only “parallel failed”
* Logs are interleaved
* It’s unclear which stage broke the build
### Solution
```
failFast + catchError
stage('Parallel Tests') {
    failFast true
    parallel {
        stage('Unit Tests') {
            steps {
                catchError(
                    buildResult: 'UNSTABLE',
                    stageResult: 'FAILURE'
                ) {
                    sh 'npm test'
                }
            }
        }
        stage('Integration Tests') {
            steps {
                sh 'npm run integration'
            }
        }
    }
}

```
### Environment Variable Problems in Jenkins Pipelines
* Are empty in sh steps
* Work in one stage but not another
* Fail inside script {} blocks
### Solution
```
Pipeline-Level (Global)
pipeline {
    agent any
    environment {
        APP_ENV = 'production'
    }
    stages {
        stage('Build') {
            steps {
                sh 'echo $APP_ENV'
            }
        }
    }
}

Stage-Level (Scoped)
stage('Deploy') {
    environment {
        REGION = 'us-east-1'
    }
    steps {
        sh 'echo Deploying to $REGION'
    }
}

Runtime (Dynamic)
script {
    env.VERSION = "v-${BUILD_NUMBER}"
}
sh 'echo $VERSION'

Common Mistake
def MY_VAR = 'test'
sh 'echo $MY_VAR'   // Won’t work

env.MY_VAR = 'test' // Correct


```
## Pipeline causing controller Out-Of-Memory & Resource Errors
Poorly designed Jenkins pipelines can **overload the Jenkins controller**, leading to:
* `java.lang.OutOfMemoryError` on the controller
* Jenkins UI becoming slow or unresponsive
* Random job failures or controller restarts
* Disk exhaustion due to excessive logs or artifacts
This commonly happens when pipelines:
* Run heavy logic inside `script {}` blocks
* Process large files or JSON in Groovy
* Print massive logs to the console
* Execute builds on the controller instead of agents
* Accumulate workspaces and build history
### Tips & Suggestions
* Move heavy work to build agents
* Avoid large Groovy data structures in `script {}`
* Limit console output (use files instead of `echo`)
* Clean workspaces regularly
```
post {
    always {
        deleteDir()
    }
}


```
* Rotate and discard old builds
* Monitor controller JVM memory (`Xmx`)
* Split large pipelines into smaller stages/jobs
* Use cloud native storage for test artifacts and reports.