dfsutil and dfsdiag: managing and diagnosing DFS Namespaces

dfsutil and dfsdiag are the two command-line tools that come with the DFS Namespaces management feature. dfsutil reads and edits namespace configuration and the two caches a client keeps; dfsdiag runs five fixed health checks against domain controllers, namespace servers and referrals.

Microsoft’s reference page for dfsutil now spends most of its length telling you which parameters the DFSN PowerShell module has replaced. That framing is genuinely useful, and it is also incomplete. The half PowerShell did not replace is exactly the half you reach for when a client cannot open \\contoso.com\namespace1, and the reference page does not show you one command from it.

This article works that boundary from both sides: which parameters have a cmdlet and which do not, the dfsutil commands Microsoft’s own DFS Namespace troubleshooting guidance types (none of which appear on the dfsutil reference page), and which one of the five dfsdiag tests quietly runs the other four.

Applies to: Windows Server 2016 / 2019 / 2022 / 2025, and Windows clients with the DFS Namespaces management tools installed

Quick answer

Three commands cover most of what you will actually type. The first two read the client caches, the third is the single dfsdiag entry point that runs the other checks for you.

rem The referral cache (PKT cache): which namespace targets this client is using right now
dfsutil /pktinfo

rem The domain cache: which trusted domains and domain controllers the client discovered
dfsutil /spcinfo

rem Point testreferral at a namespace root and it also runs testdcs, testdfsconfig and testdfsintegrity
dfsdiag /testreferral /DFSpath:\\contoso.com\namespace1

Before the first example

Four things need to be true before anything below behaves the way it is described here.

1. The tools are on the machine. Both executables arrive with the DFS Namespaces management tools, not with the OS. If nothing comes back, that feature is not installed.

where dfsutil
where dfsdiag

2. You have a namespace path to point at. Every example below uses the namespace root \\contoso.com\namespace1 and the folder \\contoso.com\namespace1\folder1. Substitute your own and keep them consistent, because several of the tests behave differently depending on whether you hand them a root or a folder.

rem A quick sanity check that the path resolves at all before you start diagnosing it
dir \\contoso.com\namespace1

3. Your account can read remote servers. Microsoft’s pages do not state an elevation requirement for either tool, but dfsdiag /testdcs and dfsdiag /testdfsconfig both query service state and registry values on every domain controller or namespace server they find. An account that cannot do that produces errors which read like configuration faults.

rem Confirm the token you are running with before blaming the namespace
whoami /groups | findstr /i "Administrators"

4. The DFSN module is present if you want the server-side half. It is part of the same management tools, and it is what replaced six of the nine dfsutil parameter families.

# Lists the DFS Namespace cmdlets available on this machine
Get-Command -Module DFSN | Measure-Object | Select-Object -ExpandProperty Count

What the DFSN module actually replaced

The dfsutil reference page is built around two tables, and the split between them is the single most useful thing on it. Six parameter families have DFSN equivalents. Three do not.

The pattern is not arbitrary. Every replaced family operates on a namespace object stored in Active Directory or on a namespace server. Every unreplaced family operates on the client you are typing at.

The module listing confirms it from the other direction. Microsoft’s DFSN module page lists 23 cmdlets, and every one of them is named for a server-side object: DfsnRoot, DfsnRootTarget, DfsnFolder, DfsnFolderTarget, DfsnAccess and DfsnServerConfiguration. Six nouns, no client noun among them.

# Group the module by noun to see the shape of what was ported
Get-Command -Module DFSN |
    Group-Object -Property Noun |
    Select-Object Count, Name

Microsoft’s own answer for those three families is to go and read the built-in help, which is worth knowing because the online reference will not tell you any more than this.

rem The reference page's own instruction for the three unreplaced families
dfsutil client /?
dfsutil diag /?
dfsutil cache /?

The commands the reference page never names

Microsoft’s DFSN access-failure guidance, KB 975440, is a working troubleshooting procedure, and it types dfsutil repeatedly. It does not use a single one of the nine parameter families above. It uses six flat switches that the dfsutil reference page never mentions.

Reading the two client caches

A DFS client keeps two caches and they fail differently. The domain cache answers “which domain controllers do I know about”. The referral cache answers “for this namespace path, which target am I being sent to”. Both are per-client and neither is visible from the server.

This is the domain cache, exactly as Microsoft prints it. Two domain controllers were found for the NetBIOS domain name CONTOSO.

[*][2003server1.contoso.com]
[*][CONTOSO]
[*][contoso.com]
[+][CONTOSO]
    [-2003server2]
    [+2003server1]
[-][contoso.com]

The markers are the whole point of the output. Entries marked with an asterisk came from the Workstation service; the rest came from DFSN referrals. Entries marked with a plus sign are the domain controllers the client is currently using.

The referral cache is the one you will read more often. This capture is the expected state after a client has opened \\contoso.com\dfsroot\link, where the root has two targets and the link has one.

Entry: \contoso.com\dfsroot
ShortEntry: \contoso.com\dfsroot
Expires in 300 seconds
UseCount: 0 Type:0x81 ( REFERRAL_SVC DFS )
    0:[\ROOTSERVER1\dfsshare] State:0x119 ( ACTIVE )
    1:[\ROOTSERVER2\dfsshare] State:0x09 ( )

Entry: \contoso.com\dfsroot\link
ShortEntry: \contoso.com\dfsroot\link
Expires in 1800 seconds
UseCount: 0 Type:0x1 ( DFS )
    0:[\fileserver\data] State:0x131 ( ACTIVE )

Three separate diagnoses come out of this one block, and they are worth separating because they lead to different places.

The five dfsdiag tests, and the one that runs the others

dfsdiag has exactly five tests. They are not five independent probes; they are layered, and /testreferral sits on top of all of them.

Which path you hand testreferral decides which tests run

This is documented on the /testreferral page and it is the most useful thing about the tool. The deeper the path, the more it does.

rem Broadest sweep: trusted domains only, nothing else needed
dfsdiag /testreferral /DFSpath:

rem Namespace root: also runs the config and integrity checks
dfsdiag /testreferral /DFSpath:\\contoso.com\namespace1

rem Folder: everything above, plus the site checks for that folder's targets
dfsdiag /testreferral /DFSpath:\\contoso.com\namespace1\folder1 /full

Practical examples

Example 1: one client cannot open the namespace, everyone else can.

The problem: a single workstation gets “The network path was not found” on \\contoso.com\namespace1 while the machine next to it opens it fine. The solution: read that client’s referral cache, because the fault is local to it and nothing on the server will show it.

rem Read the referral cache on the failing client, not on the server
dfsutil /pktinfo

rem If there is no entry for namespace1 at all, the DC never returned a referral.
rem Check which DCs this client is even talking to:
dfsutil /spcinfo

Example 2: the namespace resolves, but to a server on the other side of the WAN.

The problem: file access is slow from one branch office, and the referral cache shows the ACTIVE target is a server in head office. The solution: check whether AD agrees with the client and the server about which site everything is in.

rem What site does DFS think this root target lives in?
dfsutil /sitename:SRV-DFS-01

rem And what site does it map the complaining client's IP address to?
dfsutil /sitename:10.20.14.37

rem Then confirm the site associations agree on every DC, and that AD
rem and the server's own registry agree with each other (/full does the second part)
dfsdiag /testsites /machine:SRV-DFS-01 /full

Example 3: a site has no targets and the namespace is set to in-site referrals only.

The problem: clients in a new site get no referral at all rather than a slow one. The solution: this is the documented failure mode for the insite option, and it has its own switch.

rem Is this namespace restricted to issuing referrals inside the client's own site?
dfsutil /path:\\contoso.com\namespace1 /insite /display

Example 4: after a namespace change, some servers still hand out the old configuration.

The problem: a folder target was removed in DFS Management but clients are still being sent to it. The solution: namespace changes are written to the PDC emulator and the other servers poll for them, so this is an AD replication question before it is a DFS question.

rem Check inbound replication status for every DC in the domain
repadmin /showrepl * dc=contoso,dc=com

rem Then confirm the namespace metadata itself is consistent between DCs
dfsdiag /testdfsintegrity /DFSroot:\\contoso.com\namespace1 /recurse /full

Example 5: clear the client state so the next test starts clean.

The problem: you have changed something and the client keeps using what it cached. The solution: flush both caches, in the order Microsoft gives, and re-read them to confirm they are actually empty before you retest.

rem Flush name resolution first, then the two DFS caches
nbtstat -RR
ipconfig /flushdns
dfsutil /pktflush
dfsutil /spcflush

rem Confirm the referral cache is empty before you touch the namespace again
dfsutil /pktinfo

Parsing dfsutil output in both shells

The referral cache is readable by eye for one namespace and unreadable for thirty. Both shells can pull the ACTIVE targets out of it, and both have a trap on the way.

CMD: the brackets are part of the token

The target lines look like they are made of neat fields, and with the default delimiters they are not. The obvious tokens=1 gives you the index and both square brackets glued to the path.

delims=[] is the right answer and it has a second benefit: the line is indented, and once the space is no longer a delimiter the leading whitespace stays inside token 1 instead of shifting everything along.

rem These two lines are typed at the prompt, so the loop variable is %T.
rem The batch-file spelling of the same loop is in the callout below.
dfsutil /pktinfo > "%TEMP%\pkt.txt"
for /f "tokens=2 delims=[]" %T in ('findstr /c:"ACTIVE" "%TEMP%\pkt.txt"') do @echo %T

\ROOTSERVER1\dfsshare
\fileserver\data

PowerShell: a failed -match does not clear $Matches

The PowerShell version is a plain -match in a loop, which is fine. What is not fine is reading $Matches without checking whether the match succeeded.

$pkt = dfsutil /pktinfo
$targets = foreach ($line in $pkt) {
    if ($line -match '^\s*\d+:\[(.+?)\].*\(\s*ACTIVE\s*\)') { $Matches[1] }
}
$targets

That form is safe because the if tests the result. This is what happens when you skip that test: after a line that does not match, $Matches[1] still holds the value from the previous line that did.

$good = '    0:[\ROOTSERVER1\dfsshare] State:0x119 ( ACTIVE )'
$bad  = 'UseCount: 0 Type:0x81 ( REFERRAL_SVC DFS )'
$pattern = '^\s*\d+:\[(.+?)\]'

$r1 = $good -match $pattern
$m1 = $Matches[1]
$r2 = $bad  -match $pattern
$q2 = $?              # capture immediately: $? describes the statement just above it
$m2 = $Matches[1]

"line 1 matched : $r1"
"line 1 Matches : $m1"
"line 2 matched : $r2"
"line 2 Matches : $m2"
"`$? after it    : $q2"

line 1 matched : True
line 1 Matches : \ROOTSERVER1\dfsshare
line 2 matched : False
line 2 Matches : \ROOTSERVER1\dfsshare
$? after it    : True

Hidden gems

An empty /DFSpath: is a valid argument, not a mistake. dfsdiag /testreferral /DFSpath: with nothing after the colon is the documented way to validate that the referral list includes all trusted domains. It is the cheapest first test in the whole tool and it needs no namespace at all.

The TTL check only appears for SYSVOL and NETLOGON. Pointing /testreferral at \\contoso.com\SYSvol adds a check that the referral time to live matches the default of 900 seconds. No other path triggers it, which makes it a quick way to catch a SYSVOL or NETLOGON referral TTL that was changed years ago and forgotten.

/testdfsconfig understands clusters. On a clustered namespace server it validates three specific resource dependencies: the namespace root resource on the network name resource, the network name resource on the IP address resource, and the namespace root resource on the physical disk resource. If a clustered namespace fails after a maintenance window, that is a three-item checklist rather than a hunt.

The referral cache tells you about connectivity, not just DFS. An entry with targets listed but none marked ACTIVE is proof that the client reached a domain controller and failed to reach any file server. That single observation splits the problem in half before you touch a network capture.

Pair /sitename: with itself. Run it twice, once against a root target’s name and once against a complaining client’s IP address. If the two answers disagree with what AD Sites and Services says, you have found the cause of a mis-ordered referral without reading any DFS configuration at all.

Where this matters

• Branch office performance complaints. A client being referred across a WAN link looks exactly like a slow file server until you read the referral cache and see which target is ACTIVE.
• After a file server decommission. Removed folder targets can survive in client referral caches and in namespace metadata on lagging domain controllers, so the machine that “still goes to the old server” is usually cache plus replication.
• New AD site rollouts. Adding a site without adding a namespace or folder target in it produces no referral at all when the in-site option is set, which is why a new office sometimes cannot reach the namespace on day one.
• Clustered namespace servers after patching. A namespace root that fails to come online after a reboot usually traces to one of the three documented resource dependencies rather than to DFS itself.
• Migrating namespace administration to scripts. Knowing that the DFSN module covers the server-side objects and nothing on the client saves you writing a wrapper for a cmdlet that was never going to exist.
• Post-migration validation. After moving SYSVOL replication or rebuilding domain controllers, dfsdiag /testdcs checks the DFS Namespace service state and site-costed referral support on every DC in one pass.

Tips and limitations

• Both tools come with the DFS Namespaces management tools, not with a default Windows install. where dfsutil is the fastest way to find out whether you have them.
• The client caches are per-machine. Reading them on a server tells you nothing about the workstation that is failing, which is the single most common wasted step on this kind of call.
• The dfsutil reference page and four of the five dfsdiag pages carry an ms.date of 16 October 2017. Treat the built-in /? help as more current than the web page.
• Microsoft’s own example for /testdfsintegrity writes the root as \contoso.com\MyNamespace with one leading backslash, while every other example on every other page uses two. Use two.
• The switch casing varies between Microsoft’s pages, with /DFSPath, /DFSpath, /DFSRoot and /DFSroot all appearing. The parser does not care; do not spend time on it.
• /recurse means different things on different tests: on /testsites it walks folder targets under a root, on /testdfsintegrity it includes namespace interlinks.
• On /testreferral, /full applies only to domain and root referrals, where it compares site association information between the registry and Active Directory. On /testsites and /testdfsintegrity the same switch does something different.
• None of the five dfsdiag reference pages shows a single line of output. Run the test once in a healthy environment so you know what a clean pass looks like before you need to recognise a failure.

Quick reference

Official documentation

• dfsutil: Windows Commands | Microsoft Learn
• dfsdiag: Windows Commands | Microsoft Learn
• Troubleshoot DFSN access failures (KB 975440) | Microsoft Learn
• DFSN PowerShell module | Microsoft Learn

Related tools

• nltest Command Builder: builds the domain controller and site discovery commands you reach for when dfsdiag /testdcs or dfsutil /sitename: points at a site association problem.

Related guides

• dfsrmig: migrating SYSVOL from FRS to DFSR: the replication side of DFS, and the migration that dfsdiag /testdcs is worth running after.
• DCDiag: Active Directory troubleshooting: the broader domain controller health check to run when /testdcs reports problems on several DCs at once.
• nltest: domain controller and trust diagnostics: confirms secure channel and DC discovery before you blame the namespace.
• repadmin: Active Directory replication: the tool behind repadmin /showrepl in example 4, for when namespace changes have not reached every DC.
• net use: mapped drives from the command line: the other half of the story when a namespace path works but a mapped drive to it does not.
• where and Get-Command: finding which executable runs: how the prerequisite check above works, and what to do when the wrong copy of a tool is first on PATH.
• Active Directory troubleshooting cheat sheet: the one-page version of the domain-side checks referenced throughout this article.