My workspace directory is not being created in the expected location

Last Reviewed:2026-01-02()
2 minute readKnowledge base

Issue

Workspace directories are not being created in the expected location under $JENKINS_HOME/workspace/ for some instances. Instead, workspaces are created in the job configuration directory using the path $JENKINS_HOME/jobs/$JOB_NAME/workspace.

This prevents workspaces from being created in the standardized centralized location.

Environment

Explanation

This issue is caused by legacy configuration settings inherited from earlier installations.

When comparing config.xml files between affected and unaffected instances, a discrepancy is found in the <workspaceDir> configuration:

  • Affected instances use: <workspaceDir>${ITEM_ROOTDIR}/workspace</workspaceDir>

  • Unaffected instances use: <workspaceDir>${JENKINS_HOME}/workspace/${ITEM_FULL_NAME}</workspaceDir>

The ${ITEM_ROOTDIR} variable resolves to the job’s configuration directory ($JENKINS_HOME/jobs/$JOB_NAME), which places workspaces alongside job configuration files rather than in the centralized workspace directory.

The ${JENKINS_HOME}/workspace/${ITEM_FULL_NAME} configuration creates workspaces in a dedicated workspace directory structure, which is the expected behavior for current installations.

Resolution

Update the workspace directory configuration in the instance’s config.xml file.

  1. Access the instance’s filesystem where $JENKINS_HOME/config.xml is located.

  2. Edit the config.xml file and locate the <workspaceDir> element.

  3. Change the configuration from:

    <workspaceDir>${ITEM_ROOTDIR}/workspace</workspaceDir>
    ▼

    to:

    <workspaceDir>${JENKINS_HOME}/workspace/${ITEM_FULL_NAME}</workspaceDir>
    ▼

  4. Save the file and restart the instance for the changes to take effect.

  5. Trigger new builds to verify that workspaces are now created in the expected location under $JENKINS_HOME/workspace/.

Existing workspaces in the old location will not be automatically moved. New builds will create workspaces in the new location. Old workspace directories can be manually cleaned up if needed after verifying the new configuration works correctly.
Test this change in a lower environment before applying it to production instances.

Tested product/plugin versions

This article is part of our Knowledge Base and is provided for guidance-based purposes only. The solutions or workarounds described here are not officially supported by CloudBees and may not be applicable in all environments. Use at your own discretion, and test changes in a safe environment before applying them to production systems.