Microsoft TFS Tasks: Troubleshooting

This document describes some common troubleshooting steps to take when you encounter problems using the TFS Ant tasks.

Contents


Specify the server

All of the TFS tasks need to connect to a TFS server in order to do their work. Under some circumstances, the proper server to connect to can be inferred by the wrapped command-line tool. This is not always possible. It's best to always explicitly specify the server to connect to, either by using the global tfs.server property, or the per-task server attribute. See the TFS tasks manual for more information.

Symptoms

You get a build failure with output similar to:

[tfsworkspace] Unable to determine the source control server.

BUILD FAILED
C:\temp\anttest\build.xml:8: the CLC executable "tf" failed (error in task "tfsworkspace" used in "mytarget")

Resolution

Explicitly specify the server option, either through a global build property:

<property name="tfs.server" value="http://tfs.mycompany.com:8080" />

or through a per-task attribute:

<tfsworkspace 
	mode="create" 
	workspace="antworkspace" 
	server="http://tfs.mycompany.com:8080" />

Specify login credentials

In order to succesfully use the TFS server, the TFS command-line tool must first authenticate against the server. The tf.exe tool on Windows supports the use of Windows integrated authentication. This means that if no login credentials are explicitly specified, the credentials of the user account running the tf.exe process will be used in the login attempt. The Teamprise command line client does not currently support the use of Windows integrated authentication, so with this tool login credentials must always be specified. Additionally, even when using Windows integrated authentication the user account running tf.exe may not have the proper credentials to log into the TFS server.

Symptoms

You get a build failure with output similar to:

[tfsworkspace] ERROR [main] Application - com.teamprise.clc.exceptions.CLCException: Authentication credentials could not be determined from any cached workspace.  The workspace or login option must be provided.
[tfsworkspace] A client error occurred: Authentication credentials could not be determined from any cached workspace.  The workspace or login option must be provided.

Resolution

Explicitly specify login credentials by specifying both a "user" and "password" configuration, either through global build properties:

<property name="tfs.user" value="MYDOMAIN\myuser" />
<property name="tfs.password" value="secret" />

or through a per-task attribute:

<tfsworkspace 
	mode="create" 
	workspace="antworkspace" 
	user="MYDOMAIN\myuser"
	password="secret" />

Note: Both the user and password configuration data must be specified. If one is specified but the other is not, the one that is specified will be ignored. This is because the TFS command-line tool uses a single option to specify both the username and the password. Also, if the user account is a domain account, the domain must be specified as in the above examples.

Specify the location of the command-line executable

All of the TFS tasks work by wrapping the execution of a TFS command-line tool. (Currently, the only supported command-line tool is tf). In order to execute this command-line tool, the tasks must be able to locate it, or the tool must be in the path. When specifying the location of the command-line tool, you can specify an absolute path, a relative path, or a simple name. The best way to ensure that the tool is located is to explicitly specify the absolute location of the tool.

Symptoms

You get a build failure with output similar to:

BUILD FAILED
C:\temp\anttest\build.xml:15: the tf command [workspace] failed (CreateProcess: tf workspace -server:http://purina.teamprise.com:8080 -delete antworkspace error=2) (error in task "tfsworkspace" used in "default-target")

Resolution

Explicitly specify the absolute location of the command-line tool, either through global build properties:

<property 
	name="tfs.vc.executable" 
	value="C:\Program Files\Microsoft Visual Studio 8\Common7\IDE\tf.exe" />

or through a per-task attribute:

<tfsworkspace 
	mode="create" 
	workspace="antworkspace" 
	executable="C:\Program Files\Microsoft Visual Studio 8\Common7\IDE\tf.exe" />

Note: If you believe the executable is in the path and you still get an error similar to the one above, try running "tf" from a command prompt. If that succeeds, run Ant from that same command prompt.

Check items out before modification

When using TFS version control, keep in mind that items gotten from the server will be set read-only locally until the client explicitly performs a check-out. This is a by-design feature of TFS version control. If your Ant script needs to make a modification to a TFS versioned item, it must first perform a check-out on that item (by calling the <tfscheckout> task).

Symptoms

You get a build failure with output similar to:

default-target:
[propertyfile] Updating property file: C:\temp\anttest\files\project\test.properties

BUILD FAILED
C:\temp\anttest\build.xml:11: java.io.FileNotFoundException: C:\temp\anttest\files\project\test.properties (Access is denied)

Resolution

Before calling any Ant task that attempts to write to a file obtained by calling the <tfsget> task, first ensure that the file is writable by performing a check-out (<tfscheckout>).

Use the -verbose switch

As a last resort when troubleshooting the TFS Ant tasks, run Ant in verbose mode. This can be done by passing the -verbose switch when invoking Ant. Running Ant in verbose mode will create much more output than a normal run of Ant. This output will include debugging information from the TFS tasks (and other Ant tasks), as well as the complete stack traces for any exceptions that fail the build. If you have a problem with the TFS tasks that you can't resolve, run Ant in verbose mode and send the output along with a description of the problem to Teamprise support.