Symptoms
-
Pipeline run shows a failure like the following:
org.jenkinsci.plugins.workflow.steps.MissingContextVariableException: Required context class hudson.FilePath is missing Perhaps you forgot to surround the code with a step that provides this, such as: node
Diagnostic/Treatment
This is caused by a step execution in the Pipeline code that requires that a workspace be available - i.e. an agent and a workspace are allocated - but there is none.
In some cases, it is because the step executed is NOT within a node block.
Otherwise, it can be caused by the behavior of the post declarative directive. For example, if a pipeline is aborted while waiting on a node to be provisioned or if the node is disconnected / removed in stage. In such a case, since a workspace is not available at the time the step is executed, the post block cannot execute steps that require a workspace.
Troubleshooting
Find the faulty step / snippet
The stacktrace helps to identify the line in the Script that causes the problem. For example here it is the line 172 in the main pipeline script:
org.jenkinsci.plugins.workflow.steps.MissingContextVariableException: Required context class hudson.FilePath is missing
Perhaps you forgot to surround the code with a step that provides this, such as: node
[...]
at WorkflowScript.run(WorkflowScript:172)
at ___cps.transform___(Native Method)
Loaded Scripts / Shared Libraries
When this happens in a loaded script (from a shared library for example) the stacktrace is different and the line to look for is similar to Script<scriptNumber>.<methodName>(Script<scriptNumber>.groovy:<lineNumber>). For example:
org.jenkinsci.plugins.workflow.steps.MissingContextVariableException: Required context class hudson.FilePath is missing
Perhaps you forgot to surround the code with a step that provides this, such as: node
[...]
at Script1.myGlobalFunc(Script1.groovy:17)
at ___cps.transform___(Native Method)
In this example, although the Script1 is not very helpful the method name myGlobalFunc should help to find the culprit. Otherwise, look at the build.xml in the Build Directory to find out what Script1 refer to.
Fix the Pipeline
Make sure that the step executed is called within a node block.
In cases where the workspace might be unavailable - such as in a post declarative block - the getContext can be used to check if a workspace context exists. For example:
post { always { script { if (getContext(hudson.FilePath)) { deleteDir() } } } }
Data Collection
In order to troubleshoot the issue further:
-
collect a Support Bundle of the instance
-
collect a Build Directory of the impacted Pipeline run