VSTS Integration: Errors and Resolutions
This article provides a comprehensive list of error message and resolution that the user or IT administrator can run into on Dynamics Lifecycle Services during deployment of Build agent. Resolution in most cases is to fix configuration issues in VSTS.
Note - All of the errors related to permissions can be avoided if the personal access token associated with the Dynamics Lifecycle Services belongs to either the VSTS account owner or is the user is part of the Team foundation administrator group.
Issue - LCS deployment failing because the new build agent starts processing build request even though the deployment process hasn't finished completely.
Error Message - Post deployment error similar to "Timed out waiting for event: ProvisionWorkItem"
Before you ask for a new deployment from LCS, make sure you don't have pending builds queued. The agent pool you are trying to add the agent under should not have any active requests for build. This is so that the new build agent being deployed doesn't start processing builds while in the midst of completing the LCS deployment process causing the deployment to fail. You can follow these steps to help you avoid this issue. Go to the agent queue page and see if there are any builds queued against your existing dead or disabled agents. Eg. Here you can see there are 2 builds queued (they have not started executing yet) since there is no agent available to process the request.
Or you can use a different agent pool to create the new agent so no existing request can be processed on that machine. But then you would still have to go an delete those queued build requests if you would like the new agent to start processing them.
Issue - VSTS project could not be found
There are 3 potential reasons for this error and you need to verify all of them.
- Either the VSTS project that was connected to LCS was deleted.
- Or the user does not have access to the project any more.
- Or the token that was used in LCS has expired or has been revoked.
Issue - Invalid access token
The project does exist in VSTS but the token that was used has either expired or it has limited scope. Make sure that the token you use is created with 'All scopes' . Note that selecting 'Selected scopes' and then selecting all the options is not similar to selecting 'All scopes' in VSTS. You have to choose 'All scopes'
Issue - No more private agent slots
Need to have at least one free agent slot available. Free VSTS account comes with one private agent capacity. If you had already deployed a dev/test environment from LCS that deploys a build agent then you have already used up the free agent capacity.
- If you truly want another build agent then you can pay for more capacity. Instructions can be found here - https://www.visualstudio.com/en-us/docs/setup-admin/team-services/get-more-build-or-load-testing-vs
- On the other hand if you just care about 1 build agent but still want to deploy another dev/test environment then after you delete your previous environment you should go to your VSTS agent pool and either delete the old agent by clicking on the x. Or you can simply disable the agent by unselecting the checkbox.
Issue - Agent pool does not exist
The agent pool name provided in LCS should be a valid agent pool that already exists in your VSTS account. If you don't provide any value then we use 'Default' agent pool. This agent pool will be used to connect your build agent.
Issue - User has only stakeholder access level
In order to talk to VSTS rest API we need the user that is associated with LCS to at least have User level access (Anything more than Stakeholder).
Go to your VSTS user management page and change the access level of the user that is associated with LCS or change the user in LCS to someone that has higher access level.
Issue - User does not have administrator privilege to the agent pool
In order to be able to attach a build agent to a given agent pool, the user needs to have admin access to the agent pool. There are multiple ways to solve this problem
- Use the token for the VSTS account owner. They have permissions to everything in VSTS.
- Add the current user to Team foundation administrator group or use a token for another user that belongs to that group. No more settings are required after this and you get admin permission.
- If instead you would want to use a token with restricted access, then you need to make sure that the user has at least the following permissions -
- User access level should not be Stakeholder as mentioned above.
- User should have access to the VSTS project associated with LCS
- User should have admin access to agent pool.
User could be added directly to the Admin group
User could be added to the Agent pool administrators group
Issue - VSTS project that is connected with LCS only support GIT version control
Currently we only support TFVC for version control and not GIT. To get around this error -
- Either create a new project and select Team Foundation Version Control for the version control option
Or add TFVC as another supported version control to the existing GIT project.
Go to your project -> Code section and click on the GIT repository drop down and click on New repository
On the Create a new repository page, select the Type as TFVC and hit create
This will create a new TFVC version control for your code.
Issue - Agent name is not set with correct format
Make sure the Agent name that you have used in LCS follows the suggested pattern.
Issue - Branch name is not set with correct format
Make sure the Branch name that you have used in LCS follows the suggested pattern. Only provide the name of the branch and not a path in LCS. We use Main as the default branch name. The branch that gets created in VSTS will be of format /$<Project name>/Trunk/<Branch name>
Issue - No agent queue exists for agent pool
Normally when you create an agent pool it provides an option to create the agent queue in all projects automatically. But if you haven't selected that option or you have manually deleted the agent queues then you will have to recreate the agent queue.
Go to the settings page of your project and hit the New queue button
On the next window select the option of Using an existing pool and select the pool that you want to deploy against. Name of the agent pool will be appear in the error message.
Issue - User does not have Edit build definition permission
The user needs Edit build definition permission to be able to publish a new build definition to the configured project. You can update the settings looking up the security related to build definitions
On clicking the Security option you will see the following permissions page. Either you can add the user to one of the VSTS groups that has edit build definition or add the user directly to this project and change the Edit build definition permission to Allow. While you are at it also update the Delete build definition permission to Allow as well. When we perform this check on LCS we upload a temporary build definition to your account to validate the permissions and once it is successful we try to delete the definition. We don't throw any errors if the deletion failed as that is not a mandatory permission for the deployment to be successful. If you don’t give Delete build definition permission you might see a build definition lying around with a name similar to "Delete - AX7 Test Build <some guid>" which you can manually delete later.
Note - make sure to hit the Save changes button to save the permissions.
Issue - User does not have Use permission for agent queue.
User Should have a minimum of User permission to the queue that is associated with the agent pool (queue name will show in the error message).
Go to the settings page of your project and look up the Agent queues tab
You can either add the user to one of the groups that has the Administrator role or add the user directly at this level by hitting the add button. And then selecting either User or Administrator role. Don't select the Reader role.