DC Agent service troubleshooting

Use this article when VaultPilot DC Agent Service cannot install, connect, sync, or recover.

Service identity

Service name: VaultPilotDCAgent
Display name: VaultPilot DC Agent Service

Commands

powershell -ExecutionPolicy Bypass -File .\vaultpilot-dc-agent.ps1 -Status
powershell -ExecutionPolicy Bypass -File .\vaultpilot-dc-agent.ps1 -TailLog
powershell -ExecutionPolicy Bypass -File .\vaultpilot-dc-agent.ps1 -RepairService -PromptAgentToken

Checks

• VaultPilot is reachable from the domain-side machine.
• The bind user name is written as DOMAIN\username or username@domain.local.
• Local logs hide tokens, passwords and secret-like values.
• Repair mode rebuilds the service without printing credentials.
• Install and repair commands contain no token value and use only -PromptAgentToken.

Sync works but actions are disabled

Successful sync proves only that OUs, groups and users can be read. It does not enable account actions or upgrade the agent. Unlock account, Require password change, Assign random password now and Disable account in VaultPilot 3.0.3 need all of the following:

• the provider is connected;
• the service and its PowerShell worker are ready;
• both report the current agent version 1.2.27;
• the agent supports that action;
• you are the Owner, the license allows changes, and the target is a user account;
• the target is not a built-in account or the bind account.

An older agent can keep syncing while account actions stay unavailable. Check the version in Status, then rotate the token on the existing provider and repair with the current script. Do not create a second provider. If the server still offers an old script, reload the page without cache and download it again.

Require password change does not generate a password; it makes the user choose a new one at next sign-in. Assign random password now changes the AD password immediately. Reveal secret works only when the vault already holds a value, because the agent cannot read the current AD password.

401 Unauthorized during install or repair

If VaultPilot is reachable but the script prints Directory agent authorization failed, the agent itself was rejected; it is not an AD bind problem. Use VaultPilot 3.0.3 or newer from the official release or an internally approved build. Then rotate the token on the existing provider card and rerun the displayed repair command.

If the failure remains, the VaultPilot server log states the reason in words:

• the agent ID does not match any provider;
• the provider token was revoked;
• the provider has no active token;
• the command uses an old or wrong token.

Do not paste the real pma_ agent ID or pmt_ token into a support request. Use placeholders and rotate the token if it was exposed.

Rotating the token invalidates the old value immediately. Do not add the new token to the command; copy it separately and paste it only into the local secure PowerShell prompt.

Related

• Active Directory agent
• Domain dashboard screen
• Active Directory records screen
• Redacting support evidence

Back to Knowledge base →