Connectivity Issues¶

This page covers problems with UNC/SMB path reachability that prevent device groups from passing preflight checks or completing deployments. For deployment-specific failure codes after connectivity is confirmed see Deployment Failures.

How ntkDeploy validates paths: Path validation runs in two sequential steps — format validation (synchronous, based on path structure rules) then a connectivity check (an actual network probe of the share). The same validation is performed both from the Device Group UI and from the deployment write step.

Prerequisites¶

ntkDeploy installed and configured — see First Launch.
PowerShell access on the machine running ntkDeploy for the diagnostic commands in this guide.
Network access to the file server hosting the UNC share you are troubleshooting.

UNC Path Format Invalid¶

Symptom¶

The Device Group path field shows a red validation error immediately after typing, before any network check is attempted. Failure code: unc_invalid_format.

Cause¶

Path format validation enforces the following rules:

Rule	Example of violation
Must not be empty or have leading/trailing spaces	`" \\\\server\\share"`
Must use `\` as separator (not `/`)	`"//server/share"`
Must not contain `..` (parent directory traversal)	`"\\\\server\\share\\..\\other"`
Must match `\\\\server\\share[\\optional-path]`	`"\\server\share"` (single backslash)

Resolution¶

Correct the path so it matches the required format:

\\ServerName\ShareName\OptionalSubfolder

Examples of valid UNC paths:

\\fileserver01\ntkdrive$\configs
\\10.0.1.50\deployments
\\dc01.corp.example.com\profiles\prod

Common mistakes: - Using forward slashes: //fileserver01/ntkdrive$ → replace with \\fileserver01\ntkdrive$ - Single leading backslash: \fileserver01\share → use \\fileserver01\share - Trailing space copied from a spreadsheet: trim the field

UNC Path Not Found / Unreachable¶

Symptom¶

The connectivity badge on the Device Group path shows unreachable or the preflight check returns failure code unc_not_found. The path format is valid but ntkDeploy cannot confirm the directory exists.

Cause¶

The reachability check attempts to confirm the directory exists at the UNC path. A false result means the OS could not resolve the share — usually DNS resolution failure, wrong server hostname, or the SMB share has been removed.

Diagnostic Steps¶

Ping the server by hostname:
```
Test-Connection -ComputerName fileserver01 -Count 2
```
If this fails, the hostname does not resolve. Try the IP address instead.
Check DNS resolution:
```
Resolve-DnsName fileserver01
```
No result or NXDOMAIN means the hostname is not registered in DNS. Use the fully qualified domain name (FQDN) or the server's IP address in the UNC path.
Test SMB connectivity on port 445:
```
Test-NetConnection -ComputerName fileserver01 -Port 445
```
TcpTestSucceeded : False means the port is blocked — see Firewall Blocking Port 445.
Enumerate the share manually:
```
Get-ChildItem "\\\\fileserver01\\ntkdrive$"
```
If this returns results in PowerShell but ntkDeploy still reports unc_not_found, check that the service is running under an account with access to the share (see the Access Denied / Permission Denied section below.

Resolution¶

Correct the hostname to the FQDN or IP address.
Verify the share name exists on the server (net share on the target machine).
Confirm the server is powered on and the File and Printer Sharing service is running.

Access Denied / Permission Denied¶

Symptom¶

The connectivity badge shows permission_denied or preflight returns failure code unc_access_error (OS error code 5). The server is reachable but ntkDeploy cannot read or write to the share.

Cause¶

The write permission check catches a file-system access-denied error (OS error code 5) and returns status permission_denied. This means the Windows account running ntkDeploy has no rights on the remote share or the NTFS permission has not been granted.

Resolution¶

Confirm share-level permissions on the target server:
Open Computer Management → Shared Folders → Shares on the file server.
Right-click the share → Properties → Share Permissions.
Ensure the ntkDeploy operator's AD account (or a group it belongs to) has at least Change permission.
Confirm NTFS permissions on the target folder:
On the file server, right-click the folder → Properties → Security.
The account must have Modify (includes write and delete — required for backup file creation) or Full Control.
Run ntkDeploy as the correct user. If the tool is running as SYSTEM or a service account, grant that account the permissions above.
Check if the share requires Kerberos/NTLM. Cross-domain deployments may fail silently if Kerberos tickets cannot be obtained. Confirm klist shows a valid ticket for the target server:
```
klist
```
Re-run the Device Group preflight after changes take effect (share permission propagation is immediate; NTFS propagation on deep trees may take a moment).

Firewall Blocking Port 445¶

Symptom¶

Test-NetConnection reports TcpTestSucceeded : False on port 445, or preflight consistently returns unc_not_found or unc_access_error for all paths on a given server even though the server name resolves correctly.

Cause¶

Windows SMB uses TCP port 445. A host-based firewall (Windows Defender Firewall) or a network firewall rule is blocking inbound connections to that port on the target server.

Resolution¶

On the target file server, confirm the SMB inbound rule is enabled:

Get-NetFirewallRule -DisplayName "*File and Printer Sharing (SMB-In)*" |
  Select-Object DisplayName, Enabled, Profile

Enable it if disabled:

Enable-NetFirewallRule -DisplayName "File and Printer Sharing (SMB-In)"

If a network firewall (hardware or cloud) is in the path, work with your network team to add a rule allowing TCP 445 between the ntkDeploy workstation's subnet and the file server.
For Windows 11 / Server 2022+, verify that SMB over QUIC is not conflicting. QUIC uses UDP 443 but legacy SMB (used by ntkDeploy) requires TCP 445.

Intermittent Connectivity: Path Passes Preflight but Fails at Deploy Time¶

Symptom¶

The Device Group preflight check shows success, but the deployment fails with deploy_write_failed (or unc_access_error) when the actual write runs.

Cause¶

Connectivity checks and the write operation are not atomic. Network conditions can change between the two steps. This is especially common in: - VPN-based access where sessions time out or reconnect between steps - Wireless networks with brief drops - SMB shares with session limits where the server drops idle connections

Resolution¶

Eliminate VPN interruptions. Ensure the VPN session is stable and not set to disconnect after idle time before triggering a deployment.

Increase SMB session keepalive on the file server:

Set-SmbServerConfiguration -AutoDisconnectTimeout 0  # Disable auto-disconnect

Re-run the deployment immediately after a successful preflight to minimise the window for network state changes.
After addressing the root cause, retry the deployment — ntkDeploy will create a fresh backup before overwriting.

VPN and Remote Network Considerations¶

Scenario	Recommendation
UNC paths on a corporate intranet accessed via VPN	Connect VPN before opening ntkDeploy; keep the session alive for the duration of the deployment
Split-tunnel VPN (only some routes through VPN)	Confirm the file server subnet routes through the VPN tunnel (`route print` to inspect)
DirectAccess / Always-On VPN	Should work transparently; if `unc_not_found` occurs, check the DA health indicator
Cloud file shares (Azure Files, AWS FSx)	Confirm TCP 445 outbound is not blocked by the ISP or corporate proxy

Validating UNC Paths Manually with PowerShell¶

Use these commands to replicate what ntkDeploy's path validation does:

# 1. Check the path exists (mirrors checkReachability)
Test-Path "\\\\fileserver01\\ntkdrive$\\configs"

# 2. Check read access (mirrors checkReachability via Get-ChildItem)
Get-ChildItem "\\\\fileserver01\\ntkdrive$\\configs" -ErrorAction Stop

# 3. Check write access (mirrors checkWritePermission)
$testFile = "\\\\fileserver01\\ntkdrive$\\configs\\test_$(Get-Random).tmp"
Set-Content -Path $testFile -Value 'test' -ErrorAction Stop
Remove-Item -Path $testFile

# 4. Check SMB port reachability
Test-NetConnection -ComputerName fileserver01 -Port 445

If any of these commands fail, the corresponding preflight check in ntkDeploy will also fail.

Checking Event Viewer for SMB Errors¶

When ntkDeploy reports unc_access_error and the cause is not obvious, the Windows Event Log on the target file server provides additional SMB error details.

On the file server, open Event Viewer.
Navigate to Applications and Services Logs → Microsoft → Windows → SMBServer → Operational.
Filter for Error and Warning events around the time of the failed preflight or deployment.
Common event IDs to look for:

Event ID	Meaning
1020	SMB1 is disabled (not used by ntkDeploy, but indicates policy enforcement)
551	SMB session authentication failure
1009	A server-side error closed the SMB connection

Cross-reference timestamps with the ntkDeploy Audit Log to correlate events with specific deployment attempts.

Connectivity Issues¶

Prerequisites¶

UNC Path Format Invalid¶

Symptom¶

Cause¶

Resolution¶

UNC Path Not Found / Unreachable¶

Symptom¶

Cause¶

Diagnostic Steps¶

Resolution¶

Access Denied / Permission Denied¶

Symptom¶

Cause¶

Resolution¶

Firewall Blocking Port 445¶

Symptom¶

Cause¶

Resolution¶

Intermittent Connectivity: Path Passes Preflight but Fails at Deploy Time¶

Symptom¶

Cause¶

Resolution¶

VPN and Remote Network Considerations¶

Validating UNC Paths Manually with PowerShell¶

Checking Event Viewer for SMB Errors¶

Next Steps¶