DFS Namespace troubleshooting

Find the failed stage

A domain-based path such as \\contoso.com\Public\Software can involve a DC referral, a namespace-server referral, name resolution for the chosen target, then SMB access to that file server. Find which stage failed before changing the namespace.

Microsoft’s DFSN troubleshooting guide follows this separation.

Read the client caches before clearing them

With DFS management tools available, run on the affected client after attempting the path:

dfsutil /spcinfo
dfsutil /pktinfo
nltest /dsgetsite

/spcinfo shows the domain/DC information DFS uses; /pktinfo shows cached namespace/folder referrals, the selected target, and expiry. Save the output first. Clearing a cache can temporarily help while removing the clue that explains the problem.

Compare results from a working and failing client with the same intended site and user access. A service or scheduled task running under a different identity may have different connections and credentials. The access failure guide explains the cache views.

Test the returned share directly

If the referral selected \\FS1.contoso.com\Software, test that exact path with the affected identity. Check host resolution and TCP 445 reachability as well:

Resolve-DnsName 'FS1.contoso.com'
Test-NetConnection -ComputerName 'FS1.contoso.com' -Port 445

If direct access also fails, investigate SMB, share/NTFS permissions, authentication, and the file server. If direct access succeeds while the namespace path fails, continue with referrals and namespace configuration. Direct access is a diagnostic comparison, not a reason to permanently bypass the namespace.

Unexpected target selection often starts with sites

Check whether the client address maps to the intended AD site. Inspect site-link costs, target availability, target priority, and whether referrals exclude targets outside the client’s site. A VPN or WAN device that translates the source address can cause a client to appear in a different site.

When a preferred target returns, the client may keep using its current connection unless the configured failback behavior sends it back. Changing a referral policy won’t necessarily move an existing SMB session. See referrals and client failback.

Configuration exists in more than one place

Domain-based namespaces use AD configuration, namespace-server registry state, and shares. Standalone namespaces keep their configuration on the namespace server. A restored AD object alone does not guarantee that the corresponding server-side state and shares are intact.

Use DFS management APIs/tools for changes. Editing AD objects or deleting registry entries directly can leave an orphaned or inconsistent namespace. See DFSN configuration storage.

Inventory targets and priorities

With the DFSN PowerShell module:

Get-DfsnRoot -Path '\\contoso.com\Public'
Get-DfsnRootTarget -Path '\\contoso.com\Public'
Get-DfsnFolderTarget -Path '\\contoso.com\Public\Software' |
    Select-Object TargetPath, State, ReferralPriorityClass, ReferralPriorityRank

Root targets provide the namespace; folder targets provide the data. Check both for single points of failure. Priority class and rank can deliberately override the order suggested by site costs. See folder target inspection and target priority settings.

Back up the namespace and its dependencies

Keep an export of the namespace plus the appropriate DC/namespace-server backups. Namespace metadata, target file data, and file permissions have different recovery requirements. An export of referrals does not back up the files to which they point.

Before recreating a missing namespace, establish whether it was deleted administratively or lost through inconsistent configuration. The namespace recovery guide treats those cases separately.

DFSN does not replicate the target’s files

Two folder targets can contain different data unless something else maintains their consistency. Adding both to a namespace does not enable DFSR automatically.

Access-based enumeration controls folder visibility. Someone who already knows the path can still obtain a referral, so share and file-system permissions on the target remain essential. Namespace ABE and enumeration inside a target share are separate settings. Use explicit DFS folder view permissions for the intended visibility model, rather than assuming a hidden link protects the data.

Distinguish ordering from excluding targets

With random ordering, in-site targets are listed first and remote targets are otherwise randomized. Lowest-cost ordering ranks remote alternatives by AD site-link cost. Excluding targets outside the client’s site can instead leave the client with no normal remote alternative when local targets are unavailable.

One exception matters here: targets configured first or last among all targets can still be included when out-of-site targets would otherwise be excluded. Check the folder’s ordering and each target’s priority class/rank before deciding the returned list is wrong. The referral ordering guide documents the exception.

Get-DfsnRoot -Path '\\contoso.com\Public' | Format-List *
Get-DfsnFolder -Path '\\contoso.com\Public\Software' | Format-List *

Check site-costing, in-site referral, failback, and TTL settings alongside /pktinfo on the client. The server’s configuration tells you what it should return; the client’s cache shows what it’s using now.

Configuration latency and cache latency are different

A domain namespace change must reach the AD replica used by the namespace server, be consumed by that server, and then become visible through new client referrals. Existing cached referrals and SMB sessions can preserve the old target after the configuration itself is consistent.

Root scalability mode changes where namespace servers poll for configuration: enabled uses a nearby DC; disabled uses the PDC emulator. When only some namespace servers return an updated folder, inspect their configuration source and AD convergence instead of repeatedly flushing every client’s cache. The namespace settings reference explains the polling choice.

Export configuration without confusing it with a file backup

Writes a local export file: with DFS tools and appropriate read access:

dfsutil.exe root export \\contoso.com\Public C:\Recovery\Public-namespace.xml

Create the destination directory first. Check the saved namespace and target list, keep a copy before edits, and back up server/share configuration and file data separately. Microsoft’s DFSN configuration procedure shows the export syntax. Importing or recreating the namespace changes configuration and depends on server-side state. The XML alone won’t provide working root targets or restore their files.

Test the namespace at the failed layer

With DFS tools available, these diagnostic tests target different dependencies:

dfsdiag /testdcs /domain:contoso.com
dfsdiag /testreferral /DFSpath:\\contoso.com\Public /full
dfsdiag /testreferral /DFSpath:\\contoso.com\Public\Software
dfsdiag /testdfsintegrity /DFSroot:\\contoso.com\Public /recurse

/testdcs checks domain/DC-related DFS prerequisites; it does not compare replicated target files. /testreferral checks referrals for the specified path; /full applies to domain/root referrals and checks site-association consistency between registry and AD. /testdfsintegrity checks namespace metadata consistency and relevant overlap/configuration problems; /recurse includes namespace interlinks. Broad testing can be expensive in a large namespace. Retain failures with the exact server and path; a management-access failure is different from a successful integrity test finding a bad object.

If connectivity or site affinity is in question, run from an affected client as well as the administration network. A successful test on the root server can miss a problem on the client’s path to the DC, namespace server or file target. Keep the original client cache and direct-share comparison with the results. Changing all three layers at once makes it harder to find which one failed.