Jenkins Shared Library Load Error Fix

In this tutorial, you'll learn about Jenkins Shared Library Load Error Fix. We cover key concepts, practical examples, and best practices.

Your Jenkins pipeline fails with org.codehaus.groovy.control.MultipleCompilationErrorsException: startup failed: Expected symbol — the shared library cannot be loaded because the syntax, source, or version is wrong.

The Problem

// WRONG — incorrect shared library import
@Library('my-lib')

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                myBuild()
            }
        }
    }
}

org.codehaus.groovy.control.MultipleCompilationErrorsException:
startup failed:
Script1: 1: unexpected token: @Library

The @Library annotation must be followed by an underscore or an import statement. A bare @Library with no import causes a parser error.

Step-by-Step Fix

1. Use the correct @Library syntax

// RIGHT — @Library with underscore for global import
@Library('my-lib') _

pipeline {
    agent any

    stages {
        stage('Build') {
            steps {
                myBuild()
            }
        }
    }
}

The underscore imports all globally defined functions from the library.

2. Import specific classes

@Library('my-lib@v1.2.3') _
import com.myorg.PipelineUtils

pipeline {
    agent any

    stages {
        stage('Build') {
            steps {
                PipelineUtils.checkout()
            }
        }
    }
}

3. Configure the shared library in Jenkins

Go to Manage Jenkins > Configure System > Global Pipeline Libraries. Add your library:

• Name: my-lib (must match @Library('my-lib'))
• Default version: main or a tag like v1.0.0
• Source: Git, GitHub, GitLab
• Project repository: your library repo URL

4. Use a versioned library

// Use a specific tag
@Library('my-lib@v2.0.0') _

// Use a branch
@Library('my-lib@develop') _

5. Load the library without annotation

// Alternative to @Library — use library step
library 'my-lib@main'

pipeline {
    agent any

    stages {
        stage('Build') {
            steps {
                myBuild()
            }
        }
    }
}

Expected output:

[Pipeline] load
[Pipeline] // load
[Pipeline] // stage
[Pipeline] // stage
[Pipeline] End of Pipeline
Finished: SUCCESS

Prevention Tips

• Always add _ after @Library('name')
• Configure shared libraries in Jenkins UI before using them
• Use version tags (@v1.2.3) for production pipelines
• Test library loading with library 'my-lib' step in a scripted pipeline
• Check the library source repository URL and credentials

Common Mistakes with shared library

1. Mixing let bindings with <- bindings in do notation, producing type errors
2. Overlapping type class instances that cause GHC to reject the program with ambiguous dispatch errors
3. Non-exhaustive pattern matches that compile with warnings then crash at runtime

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