Description
When running an agent on a Windows resource the following error message is reported:
The agent was unable to map the UNC workspace to a drive letter: The agent cannot map the workspace to a drive letter in the impersonation context because the agent is running as LocalSystem and a mapping already exists for the drive. This is not a supported configuration. Please change the service to run as some other user or do not run steps with impersonation.
Solution
Use a workspace mapping some drive letter for all steps that run without impersonation. Use a different workspace with a different drive letter for all steps that run with impersonation. If you don’t overlap drive letter usage for these two contexts, you’ll avoid the issue.
Explanation
When the agent runs a step (without impersonation), it sets the working directory to the workspace directory by default. The agent maps the drive letter in preparation for running the step command because CMD requires that the working directory be on a drive-path, not a UNC path. After that setup is done, the step is run.
When the agent is done, the agent leaves the drive-mapping enabled, expecting that some other step will need it in the future, and the agent can save the effort of mapping at that point. If a step comes in with a different use for that drive letter, the agent unmaps the drive and remaps it to the new path.
When the agent runs a step with impersonation, the same setup is performed, but in the impersonation context. Thus, a new Windows session is created, the drive is mapped in that session, the step runs, and when it’s done, the session is destroyed (effectively unmapping the drive letter in that session). This works fine when the agent user is not LocalSystem. Steps can run concurrently with and without impersonation using the same drive letters because the Windows sessions are independent of one another.
When the agent user is LocalSystem, however, the agent’s session and the impersonation session aren’t 100% independent. Drive mappings in the main session leak to the impersonation session. So if a step had run on the agent previously (without impersonation) and a step now runs with impersonation for some workspace using the same drive letter, the impersonation context can’t map the drive letter because it is already in use. Incidentally, the impersonation context can’t use the inherited drive letter because it’s not in a usable state. The impersonation context can’t unmap it prior to doing its own mapping either. It is a zombie drive letter that uses a slot and can’t be used for anything nor can it be gotten rid of.