Jenkins shared library: why the stack trace points to `vars/`, not Jenkinsfile

Jenkins Pipeline shared libraries help teams avoid copying the same Groovy code across repositories. But when the pipeline fails, the stack trace often points to a file in vars/ or src/, not to the Jenkinsfile.

For the MR author, that is confusing: “I changed one line in the app. Why is Jenkins yelling about a shared library?”

Shared library primer

A shared library is reusable Groovy code for Jenkins Pipeline. The vars/ directory usually contains friendly pipeline steps such as buildDockerImage(), while src/ contains classes and helper logic. The Jenkinsfile calls those functions, but the error can happen inside the library.

Why the stack trace is confusing

1. Parameter error. The Jenkinsfile passed null or a wrong map, and the failure happened inside vars/deploy.groovy.

2. Library bug. The shared library changed, and an older Jenkinsfile is no longer compatible.

3. CPS stack trace noise. Jenkins transforms pipeline code, so traces contain internal calls that do not help a newcomer.

4. Sandbox blocked a method. It looks like a code bug, but the real issue is Script Security approvals.

5. Wrong library version. The repo may use a branch/tag different from the one the team expects.

What to inspect

• Which shared library version was loaded.
• Which vars/ function the Jenkinsfile called.
• Which parameters were passed.
• The first application-level stack trace line before Jenkins/CPS internals.
• Sandbox or security approval errors.

Minimal example

@Library('company-ci@v3') _

pipeline {
  stages {
    stage('Build') {
      steps {
        buildDockerImage(imageName: env.IMAGE_NAME)
      }
    }
  }
}

If IMAGE_NAME is empty, the stack trace may point to vars/buildDockerImage.groovy, but the primary cause is a missing Jenkinsfile/environment parameter.

Where Exlogare fits

Raw Jenkins console logs are often too noisy for the MR author. Exlogare can receive console output, find the useful stack trace slice, and return a short RCA: “shared library step received empty imageName; check env/parameters.” Setup is described in Jenkins ingest.

Related reading

• Self-hosted runner vs shared runner: what changes in CI logs
• CI artifacts and logs: what to keep, and what not to upload to S3 as-is

Checklist

• Find the shared library version.
• Separate parameter errors from library bugs.
• Ignore internal CPS noise until the first useful line.
• Check sandbox approvals.
• Give the MR author a short RCA, not the full console log.