KBEC-00077 - Agent wrapper and impersonation debug

Article ID:360032831852
2 minute readKnowledge base


Some CloudBees CD (CloudBees Flow) agent failures produce no error messages. To determine more information about the context or source of the difficulty, "wrapper debug" can be turned on.


Example error message:

Step error [AgentInternalError]: unable to run the command on the agent
Unspecified internal error on the agent: ecimpersonate: error reading ecwrapper pid from su output: TIMEOUT

Post-4.2 Solution on Linux and Windows

Starting from version 4.2, a java agent is introduced in CloudBees CD (CloudBees Flow). The Java agent starts up and it launches the C++ agent binary directly. So the settings mentioned above is no longer valid because runAgent.sh (or runAgent.bat) is no longer called to start the C++ agent.

In order to enable impersonate debug, we need to add environment variables by adding the following lines in wrapper.conf :


Then restart the agent. If the problem reoccurs, find the ecwrapper.log.nnnnn or ecimp.log.nnnnn file in the workspace and send it to support@cloudbees.com for analysis.

This applies to Linux and Windows only. The java agent is NOT introduced in mac agents.

Solution on Mac

Add following entry to /Library/LaunchDaemons/ecmdrAgent.plist:


Restart the agent.

Pre-4.2 Solution on Linux

Create an environment variable in the agent for debug logging. The log files will be created in the workspace directory.

  1. In the CloudBees CD (CloudBees Flow) bin directory, by default in "/opt/electriccloud/electriccommander/bin", edit runAgent.sh to add the following lines before starting the agent:

    • to debug the wrapper (note, the value of the file ends in a "period" character):


      There will be one file per step called ecwrapper.log.<jobStepId>.

    • to debug impersonation (UNIX only):

        export ECIMP_DEBUGFILE

      There will be one file per step called ecimp.log.<jobStepId>.

    • to extend the su impersonation time from 120 seconds (UNIX only):

        ECIMP_READTIMEOUT=300 #number of seconds to wait for su to complete
        export ECIMP_READTIMEOUT
  2. Restart the agent (requires root access)

Pre-4.2 Solution on Windows

The solution is the same as on Linux with the following differences:

  1. the file name is runAgent.bat

  2. the file by default is found in "C:\Program Files\Electric Cloud\ElectricCommander\bin"