Jenkins Declarative Pipeline Syntax Error Fix

In this tutorial, you'll learn about Jenkins Declarative Pipeline Syntax Error Fix. We cover key concepts, practical examples, and best practices.

Your Jenkins pipeline fails immediately with WorkflowScript: 1: Expected a step @ line ... — the declarative pipeline syntax is invalid. Jenkins is strict about the structure of pipeline blocks.

The Problem

// WRONG — missing 'steps' block
pipeline {
    agent any

    stage('Build') {
        echo 'Building...'
    }
}

WorkflowScript: 7: Expected a step @ line 7, column 5.
   stage('Build') {
   ^

In declarative pipelines, stage blocks must contain a steps block. Direct steps inside stage are not allowed.

Step-by-Step Fix

1. Add the steps block

pipeline {
    agent any

    stages {
        stage('Build') {
            steps {
                echo 'Building...'
            }
        }
    }
}

2. Use post for cleanup actions

pipeline {
    agent any

    stages {
        stage('Build') {
            steps {
                sh 'npm build'
            }
        }
    }

    post {
        success {
            echo 'Build succeeded!'
        }
        failure {
            echo 'Build failed!'
        }
        always {
            cleanWs()
        }
    }
}

3. Use correct directive syntax

// WRONG — 'when' before 'steps' with no block
stage('Test') {
    when { branch 'main' }
    steps {
        sh 'npm test'
    }
}

// RIGHT — 'when' is a directive at stage level
pipeline {
    agent any

    stages {
        stage('Test') {
            when {
                branch 'main'
            }
            steps {
                sh 'npm test'
            }
        }
    }
}

4. Handle parameters and environment

pipeline {
    agent any

    parameters {
        string(name: 'BRANCH', defaultValue: 'main', description: 'Branch to deploy')
        choice(name: 'ENV', choices: ['staging', 'production'], description: 'Environment')
    }

    environment {
        REGISTRY = 'registry.example.com'
    }

    stages {
        stage('Deploy') {
            when {
                branch params.BRANCH
            }
            steps {
                sh "deploy.sh ${params.ENV}"
            }
        }
    }
}

Expected output:

Started by user admin
[Jenkins] Building in workspace /var/lib/jenkins/workspace/myapp
[Pipeline] // stage
[Pipeline] // stage
[Pipeline] // stage
[Pipeline] End of Pipeline
Finished: SUCCESS

Prevention Tips

• Use the Pipeline Syntax Generator in Jenkins UI at /pipeline-syntax/
• Validate Jenkinsfiles with curl -X POST -H "Content-Type: text/x-yaml" --data-binary @Jenkinsfile http://localhost:8080/pipeline-model-converter/validate
• Always wrap steps inside steps { } in declarative pipelines
• Use post { } instead of try-catch for cleanup
• Use script { } blocks for complex Groovy logic inside declarative pipelines

Common Mistakes with declarative pipeline

1. Non-exhaustive pattern matches that compile with warnings then crash at runtime
2. Misunderstanding that String is [Char] with poor performance for large text operations
3. Using foldl instead of foldl' causing stack overflow on large lists

These mistakes appear frequently in real-world JENKINS code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ