Jenkins "WorkflowScript: unexpected token" - Fix Jenkinsfile Syntax
Jenkins could not even parse your Jenkinsfile. The Groovy compiler hit a token it did not expect - usually an unbalanced brace, a bad quote, or a directive in the wrong place - and the pipeline failed before any stage ran.
What this error means
The build fails immediately at "Compiling pipeline" / "Loading pipeline" with a WorkflowScript compilation error pointing at a line and column. No stage executes because the script never compiled. The same Jenkinsfile fails identically every time.
org.codehaus.groovy.control.MultipleCompilationErrorsException: startup failed:
WorkflowScript: 18: unexpected token: } @ line 18, column 1.
}
^
1 errorDiagnose it: agent, workspace, or sandbox?
Declarative pipeline failures usually come from the environment rather than the script: no matching agent, a dirty reused workspace, or the Groovy sandbox rejecting a method.
// print what the agent actually is
sh 'hostname && whoami && pwd && java -version'
sh 'env | sort | head -40'
// workspaces are REUSED between builds by default
cleanWs()Common causes
Unbalanced braces or parentheses
A missing or extra }/) from an edited stage, steps, or script block shifts the parser, and it reports the error at the line where the mismatch becomes unrecoverable - often a few lines after the real mistake.
Broken string quoting
An unterminated "..." or a ${...} interpolation inside single quotes (which Groovy does not interpolate) confuses the lexer and produces an unexpected-token error.
A declarative directive in the wrong place
In a declarative pipeline, putting a step outside steps {}, or environment/when in an invalid position, breaks the grammar the declarative parser expects.
How to fix it
Validate the Jenkinsfile against the controller
The linter compiles the file with the same parser the build uses, so it reports the exact line without burning a build.
# CLI linter (needs a crumb on CSRF-protected controllers)
curl -X POST -F "jenkinsfile=<Jenkinsfile" https://jenkins.example.com/pipeline-model-converter/validateBalance braces and fix quoting
- Open the reported line, then scan upward for the unclosed
{,(, or string. - Use double quotes when you need
${...}interpolation; single quotes are literal in Groovy. - Re-indent the file so block boundaries are visible - most brace errors are obvious once indentation is correct.
Keep declarative structure strict
Declarative pipelines only allow specific directives at each level. Put executable steps inside steps {}, and wrap arbitrary Groovy in a script {} block.
pipeline {
agent any
stages {
stage('Build') {
steps {
sh 'make build'
script { def v = readFile('VERSION').trim() }
}
}
}
}How to prevent it
- Lint the Jenkinsfile in a pre-merge check with the pipeline-model-converter validator.
- Use the Jenkins VS Code/IDE Groovy support or "Replay" to iterate on syntax.
- Keep the Jenkinsfile small; move logic into a shared library that can be unit-tested.