Skip to content

Error Codes

Jump to bottom
TheAbider edited this page Mar 13, 2026 · 3 revisions

Error Codes

RackStack uses structured error codes to help identify and resolve issues quickly. Each error displays a code, description, and a link to this page.

Error Code Format

Errors follow the pattern RS-XXXX where the first digit indicates the category:

Range Category
RS-1xxx Core / System
RS-2xxx Networking
RS-3xxx Security
RS-4xxx Roles / Features
RS-5xxx VM Pipeline
RS-6xxx Storage / Cluster
RS-7xxx Configuration / Export
RS-8xxx Agent / External

Core / System (RS-1xxx)

RS-1001

Script requires administrative privileges

Cause: RackStack was launched without "Run as Administrator." Most operations (network configuration, Hyper-V, disk management, firewall rules) require elevated privileges on Windows Server.

Resolution:

  • Right-click PowerShell and select Run as Administrator, then relaunch RackStack.
  • If running from a scheduled task, ensure the task is configured with Run with highest privileges.
  • On Server Core, launch powershell.exe from an elevated command prompt.

RS-1002

defaults.json parse error

Cause: The defaults.json file contains invalid JSON syntax. Common issues include trailing commas, unescaped backslashes in file paths, missing closing braces, or BOM/encoding problems.

Resolution:

  • Validate the file with Get-Content defaults.json | ConvertFrom-Json to see the exact parse error.
  • Check for trailing commas after the last property in any object or array.
  • Ensure file paths use escaped backslashes (\\) or forward slashes (/).
  • Re-copy from defaults.example.json and reapply your customizations if the file is corrupted.

RS-1003

Module load failure

Cause: One or more RackStack modules failed to load during initialization. This can happen if a .ps1 file is corrupted, missing UTF-8 BOM encoding, or contains syntax errors introduced by manual editing.

Resolution:

  • Check the error details for the specific module number and filename.
  • Re-download RackStack from the latest release to replace corrupted files.
  • If running from source, ensure all .ps1 files are saved with UTF-8 BOM encoding.
  • Run Get-Content -Path <module>.ps1 | Out-Null to verify the file parses without errors.

RS-1004

PowerShell version unsupported

Cause: RackStack requires Windows PowerShell 5.1 or later. The detected version is too old, or the script is running under an incompatible host (e.g., PowerShell Core 6.x without required Windows modules).

Resolution:

  • Run $PSVersionTable.PSVersion to check your current version.
  • Install WMF 5.1 on Server 2012 R2 from the Microsoft Download Center.
  • Use Windows PowerShell 5.1 (powershell.exe), not PowerShell 7 (pwsh.exe), for full compatibility with Windows Server management cmdlets.

RS-1005

Transcript start failed

Cause: RackStack could not start a PowerShell transcript for session logging. The transcript output directory may not exist, may lack write permissions, or another transcript may already be active.

Resolution:

  • Verify the log directory exists and the current user has write access.
  • Run Stop-Transcript to end any existing transcript session, then relaunch.
  • Check available disk space on the target drive.

RS-1006

Configuration directory inaccessible

Cause: RackStack cannot read or write to its configuration directory. The directory may not exist, the path may be on an unavailable network share, or NTFS permissions prevent access.

Resolution:

  • Verify the configuration path exists with Test-Path.
  • If the path is on a network share, confirm connectivity and that the share is accessible from this session.
  • Check NTFS permissions with Get-Acl <path> and ensure the running account has read/write access.
  • Run RackStack from a local directory if network storage is unreliable.

RS-1007

Invalid CLI parameter

Cause: A command-line argument passed to RackStack is not recognized or has an invalid value. This includes misspelled parameter names, missing required values, or conflicting flags.

Resolution:

  • Run RackStack with -Help to see available parameters and their expected values.
  • Check for typos in parameter names (PowerShell parameters are prefixed with -).
  • If using batch mode, verify the parameter matches a supported batch operation.

RS-1008

Batch config profile parse error

Cause: The batch configuration profile (JSON or CSV) contains invalid syntax or references settings that do not exist. The file may have been manually edited with errors or exported from an incompatible version.

Resolution:

  • Validate JSON profiles with Get-Content profile.json | ConvertFrom-Json.
  • For CSV profiles, ensure headers match expected column names exactly.
  • Re-export the profile from the current version of RackStack to ensure compatibility.
  • Check the batch mode documentation for the expected profile schema.

RS-1009

Windows Update operation failed

Cause: A Windows Update scan or installation failed. The Windows Update service may be stopped, the update catalog may be unreachable, or a previous update is pending a reboot before new updates can be installed.

Resolution:

  • Restart the Windows Update service: Restart-Service wuauserv.
  • Check for pending reboots: Test-Path 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Component Based Servicing\RebootPending'.
  • Reboot the server and retry if a reboot is pending.
  • Run sfc /scannow and DISM /Online /Cleanup-Image /RestoreHealth to repair component store corruption.
  • Verify internet connectivity to Microsoft Update servers.

Networking (RS-2xxx)

RS-2001

No physical network adapters found

Cause: RackStack could not detect any physical network adapters. All adapters may be disabled, drivers may not be installed, or the server may only have virtual adapters visible.

Resolution:

  • Run Get-NetAdapter -Physical to see what Windows detects.
  • Check Device Manager for adapters with missing or failed drivers.
  • Install the correct NIC drivers for your hardware (Intel, Broadcom, Mellanox, etc.).
  • On Hyper-V hosts, ensure you are running RackStack in the management OS, not inside a VM.

RS-2002

Invalid IP address format

Cause: The IP address entered is not a valid IPv4 address. It may contain non-numeric characters, octets outside the 0-255 range, or an incorrect number of octets.

Resolution:

  • Enter the address in standard dotted-decimal notation (e.g., 192.168.1.10).
  • Verify each octet is between 0 and 255.
  • Do not include the subnet mask or CIDR prefix with the IP address if prompted separately.

RS-2003

Invalid subnet mask or CIDR prefix

Cause: The subnet mask or CIDR prefix length is not valid. Common mistakes include non-contiguous subnet masks, CIDR values outside 1-32, or entering a subnet mask when a prefix length is expected.

Resolution:

  • Use standard subnet masks (e.g., 255.255.255.0) or CIDR prefix lengths (e.g., 24).
  • For CIDR, enter only the number (1-32), not the slash.
  • Common mappings: /24 = 255.255.255.0, /16 = 255.255.0.0, /8 = 255.0.0.0.

RS-2004

VLAN creation failed

Cause: The VLAN could not be created on the specified network adapter. The adapter may not support 802.1Q VLAN tagging, the VLAN ID may be out of range (1-4094), or the adapter may be part of a SET team that requires a different configuration approach.

Resolution:

  • Verify adapter VLAN support: Get-NetAdapterAdvancedProperty -Name <adapter> -RegistryKeyword VlanID.
  • If the adapter is in a SET team, create the VLAN on the virtual switch instead of the physical adapter.
  • Ensure the VLAN ID is between 1 and 4094 and matches your switch configuration.
  • Check that the physical switch port is configured as a trunk or tagged for the target VLAN.

RS-2005

SET team creation failed

Cause: Switch Embedded Teaming (SET) creation failed. SET requires Hyper-V to be installed, adapters must be the same speed, and the adapters must not already be in another team or bound to a virtual switch.

Resolution:

  • Verify Hyper-V is installed: Get-WindowsFeature Hyper-V.
  • Ensure selected adapters are the same link speed and are not already part of a team.
  • Remove existing virtual switches on the target adapters: Remove-VMSwitch.
  • Check that adapters are connected and link-up: Get-NetAdapter | Where-Object Status -eq 'Up'.

RS-2006

iSCSI target unreachable

Cause: The iSCSI target portal did not respond. The target IP may be incorrect, the iSCSI target service may be down, a firewall may be blocking port 3260, or there is no network path to the target.

Resolution:

  • Test basic connectivity: Test-NetConnection -ComputerName <target-ip> -Port 3260.
  • Verify the iSCSI initiator service is running: Get-Service MSiSCSI.
  • Start the service if stopped: Start-Service MSiSCSI; Set-Service MSiSCSI -StartupType Automatic.
  • Check firewall rules on both the initiator and target sides for TCP port 3260.

RS-2007

DNS configuration failed

Cause: DNS server addresses could not be set on the specified adapter. The adapter may not exist, the interface index may have changed, or the DNS addresses are unreachable.

Resolution:

  • Set DNS manually: Set-DnsClientServerAddress -InterfaceAlias <adapter> -ServerAddresses @('8.8.8.8','8.8.4.4').
  • Verify the adapter name is correct: Get-NetAdapter | Select-Object Name, InterfaceIndex.
  • Test DNS server reachability: Test-NetConnection -ComputerName <dns-ip> -Port 53.

RS-2008

Hostname change failed

Cause: The computer rename operation failed. The new hostname may contain invalid characters, exceed 15 characters (NetBIOS limit), or the current user may lack permission to rename domain-joined machines.

Resolution:

  • Use only alphanumeric characters and hyphens (no underscores or spaces), max 15 characters.
  • For domain-joined servers, provide domain admin credentials when prompted.
  • Rename manually: Rename-Computer -NewName <name> -Restart.
  • A reboot is required for the change to take effect.

RS-2009

Domain join failed

Cause: The server could not join the Active Directory domain. Common causes are incorrect credentials, DNS misconfiguration (cannot resolve the domain), a missing computer account, or network connectivity issues to a domain controller.

Resolution:

  • Verify DNS points to a DC: Resolve-DnsName <domain.fqdn> should return DC IP addresses.
  • Test DC connectivity: Test-NetConnection -ComputerName <dc-ip> -Port 389.
  • Ensure the account has permission to join computers to the domain (default limit is 10 per user).
  • Pre-stage the computer account in AD if the join quota is reached.

RS-2010

NTP synchronization failed

Cause: The Windows Time service could not synchronize with the specified NTP server. The server may be unreachable, UDP port 123 may be blocked, or the time service is not configured correctly.

Resolution:

  • Test NTP server reachability: w32tm /stripchart /computer:<ntp-server> /samples:3.
  • Restart the time service: Restart-Service W32Time.
  • Reconfigure manually: w32tm /config /manualpeerlist:"<server>" /syncfromflags:manual /reliable:yes /update.
  • Ensure UDP port 123 is open in the firewall.

RS-2011

Network connectivity test failed

Cause: A network connectivity test (ping, TCP connection, or DNS resolution) did not succeed. The target host may be down, a firewall may be blocking traffic, or there is a routing issue between the source and destination.

Resolution:

  • Test basic connectivity: Test-NetConnection -ComputerName <target>.
  • Check the local routing table: Get-NetRoute to verify a route exists to the destination network.
  • Verify the default gateway is configured and reachable.
  • Check Windows Firewall on both endpoints for blocking rules.

RS-2012

Remote Desktop configuration failed

Cause: Remote Desktop could not be enabled or configured. The registry key or firewall rule modification failed, the TermService may be disabled, or Group Policy is overriding the local configuration.

Resolution:

  • Check if Group Policy is blocking RDP: gpresult /H gpreport.html and review Remote Desktop policies.
  • Manually enable via registry: Set-ItemProperty -Path 'HKLM:\System\CurrentControlSet\Control\Terminal Server' -Name 'fDenyTSConnections' -Value 0.
  • Enable the firewall rule: Enable-NetFirewallRule -DisplayGroup 'Remote Desktop'.
  • Start the service: Set-Service TermService -StartupType Automatic; Start-Service TermService.

RS-2013

Network diagnostic port test failed

Cause: A TCP port connectivity test failed during network diagnostics. The target host may be unreachable, the port may be filtered by a firewall, or the socket connection timed out.

Resolution:

  • Verify basic connectivity: Test-Connection <host>.
  • Test the port manually: Test-NetConnection -ComputerName <host> -Port <port>.
  • Check firewall rules on both source and destination.
  • Increase the timeout if the target is on a high-latency link.

RS-2014

Network trace route failed

Cause: A traceroute operation failed during network diagnostics. The target may be unreachable, ICMP may be blocked, or the network path has too many hops.

Resolution:

  • Run traceroute manually: tracert <host>.
  • Check if ICMP is allowed through firewalls along the path.
  • Try Test-Connection -Traceroute <host> (PowerShell 6+).
  • If internal, check routing tables and gateway configuration.

Security (RS-3xxx)

RS-3001

Firewall profile configuration failed

Cause: A Windows Firewall profile (Domain, Private, or Public) could not be configured. The firewall service may be managed by Group Policy, the service may be stopped, or the requested state conflicts with another policy.

Resolution:

  • Check if GPO controls firewall: Get-NetFirewallProfile | Select-Object Name, PolicyStore.
  • Verify the firewall service: Get-Service MpsSvc.
  • If managed by GPO, changes must be made at the domain policy level, not locally.
  • Configure manually: Set-NetFirewallProfile -Profile Domain -Enabled True.

RS-3002

Password does not meet complexity requirements

Cause: The password entered does not satisfy the local or domain password policy. Windows typically requires minimum 8 characters, with at least three of: uppercase, lowercase, digits, and special characters.

Resolution:

  • Check the current policy: net accounts (local) or Get-ADDefaultDomainPasswordPolicy (domain).
  • Ensure the password includes uppercase, lowercase, numbers, and special characters.
  • The password must not contain the username or display name.
  • Increase password length if the policy requires more than 8 characters.

RS-3003

Local admin account creation failed

Cause: A local administrator account could not be created. The username may already exist, may be reserved (e.g., "Administrator", "Guest"), or the password does not meet policy requirements.

Resolution:

  • Check if the account already exists: Get-LocalUser -Name <username>.
  • Use a unique username that is not a built-in account name.
  • Ensure the password meets complexity requirements (see RS-3002).
  • Create manually: New-LocalUser -Name <user> -Password (ConvertTo-SecureString '<pass>' -AsPlainText -Force).

RS-3004

Defender exclusion path not found

Cause: The path specified for a Windows Defender exclusion does not exist on the filesystem. Defender requires valid, existing paths for file/folder exclusions.

Resolution:

  • Verify the path exists: Test-Path '<exclusion-path>'.
  • Create the directory first if it will be used later: New-Item -ItemType Directory -Path '<path>'.
  • Use the full absolute path, not a relative path or environment variable.
  • Add the exclusion manually: Add-MpPreference -ExclusionPath '<path>'.

RS-3005

BitLocker encryption failed

Cause: BitLocker could not be enabled on the target volume. The system may lack a TPM, the volume may not meet BitLocker requirements, or the BitLocker feature is not installed.

Resolution:

  • Check TPM status: Get-Tpm.
  • Install the BitLocker feature: Install-WindowsFeature BitLocker -IncludeManagementTools.
  • For servers without TPM, enable the "Allow BitLocker without a compatible TPM" Group Policy.
  • Ensure the volume is formatted NTFS and is not a system-reserved partition.

RS-3006

Credential validation failed

Cause: The supplied credentials could not be validated. The username or password is incorrect, the account may be locked out or disabled, or the domain controller is unreachable for domain accounts.

Resolution:

  • Verify the username format (use DOMAIN\User or user@domain.fqdn for domain accounts).
  • Check if the account is locked: Get-ADUser <user> -Properties LockedOut or Get-LocalUser <user>.
  • Unlock if needed: Unlock-ADAccount <user> or Enable-LocalUser <user>.
  • For domain accounts, confirm a domain controller is reachable.

RS-3007

Defender exclusion operation failed

Cause: A Windows Defender exclusion could not be added or removed. The path may not exist, the Defender service may not be running, or another security product has taken over real-time protection and disabled the Defender PowerShell module.

Resolution:

  • Verify Defender is active: Get-MpComputerStatus | Select-Object RealTimeProtectionEnabled.
  • Check if the path exists before adding: Test-Path <path>.
  • Add exclusion manually: Add-MpPreference -ExclusionPath '<path>'.
  • If a third-party AV is installed, Defender exclusions may not apply.

RS-3008

BitLocker recovery key backup failed

Cause: The BitLocker recovery key could not be saved to Active Directory or exported to a file. The server may not be domain-joined, AD backup may not be configured in Group Policy, or the target file path is not writable.

Resolution:

  • Save manually to file: (Get-BitLockerVolume -MountPoint C:).KeyProtector | Where-Object { $_.KeyProtectorType -eq 'RecoveryPassword' } | Select-Object -ExpandProperty RecoveryPassword.
  • Back up to AD: Backup-BitLockerKeyProtector -MountPoint C: -KeyProtectorId <id>.
  • Ensure the server is domain-joined if using AD backup.
  • Check write permissions on the target export path.

Roles / Features (RS-4xxx)

RS-4001

Hyper-V role not installed

Cause: A Hyper-V operation was attempted but the Hyper-V role is not installed on this server. VM management, virtual switches, and VHD operations all require Hyper-V.

Resolution:

  • Install Hyper-V: Install-WindowsFeature Hyper-V -IncludeManagementTools -Restart.
  • A reboot is required after installation.
  • Verify hardware virtualization is enabled in BIOS/UEFI (Intel VT-x or AMD-V).
  • Confirm after reboot: Get-WindowsFeature Hyper-V | Select-Object InstallState.

RS-4002

Windows feature installation failed

Cause: A Windows Server feature could not be installed. The feature may not be available on this OS edition (e.g., Standard vs. Datacenter), the component store may be corrupted, or a reboot is pending from a previous installation.

Resolution:

  • Check available features: Get-WindowsFeature | Where-Object Name -like '*<feature>*'.
  • If a reboot is pending, restart the server and retry.
  • Repair the component store: DISM /Online /Cleanup-Image /RestoreHealth.
  • Check the CBS log at C:\Windows\Logs\CBS\CBS.log for detailed failure reasons.

RS-4003

MPIO feature not available

Cause: Multipath I/O (MPIO) is not installed or not available on this edition of Windows Server. MPIO is required for redundant iSCSI or Fibre Channel paths.

Resolution:

  • Install MPIO: Install-WindowsFeature Multipath-IO -Restart.
  • After reboot, add iSCSI support: Enable-MSDSMAutomaticClaim -BusType iSCSI.
  • Verify: Get-WindowsFeature Multipath-IO.
  • MPIO is available on all Server editions but must be explicitly installed.

RS-4004

Failover Clustering validation failed

Cause: The cluster validation tests did not pass. Common failures include networking issues between nodes, incompatible storage configurations, mismatched OS versions, or DNS resolution problems.

Resolution:

  • Run validation manually: Test-Cluster -Node <node1>,<node2> -ReportName C:\ClusterValidation.
  • Review the HTML validation report for specific test failures.
  • Ensure all nodes run the same Windows Server version and patch level.
  • Verify all nodes can resolve each other by name and all required ports are open.

RS-4005

Deduplication not supported on this OS

Cause: Data Deduplication is not available on this operating system. It requires Windows Server 2012 R2 or later and is not available on Windows client editions.

Resolution:

  • Verify OS: Get-ComputerInfo | Select-Object WindowsProductName.
  • Install the feature: Install-WindowsFeature FS-Data-Deduplication.
  • Deduplication is supported on NTFS volumes only (not ReFS).
  • Minimum volume size is typically 2 GB with data older than a configured age.

RS-4006

Storage Replica requires Server 2016+

Cause: Storage Replica was requested but is only available on Windows Server 2016 and later. On Server 2016/2019 Standard, it is limited to a single partnership with one volume up to 2 TB.

Resolution:

  • Verify OS version: [System.Environment]::OSVersion.Version.
  • Install the feature: Install-WindowsFeature Storage-Replica -IncludeManagementTools -Restart.
  • For unlimited volumes, use Windows Server Datacenter edition.
  • Ensure all partner servers run the same or compatible Server version.

RS-4007

Cluster creation failed

Cause: A new failover cluster could not be created. Common causes include missing prerequisites (AD computer object permissions, DNS), network misconfiguration, or validation test failures that prevent cluster formation.

Resolution:

  • Run cluster validation first: Test-Cluster -Node <node1>,<node2>.
  • Ensure the cluster CNO (Computer Name Object) can be created in AD — verify Create Computer Objects permission on the target OU.
  • Check that all nodes have at least one common network for cluster communication.
  • Review the validation report at C:\Windows\Cluster\Reports\ for specific failures.
  • Ensure DNS is working: all nodes must resolve each other by FQDN.

RS-4008

Cluster node operation failed

Cause: A cluster node operation (join, evict, pause, resume, drain) failed. The node may be unreachable, the cluster service may not be running, or workloads could not be migrated off the node before draining.

Resolution:

  • Check cluster service status: Get-Service ClusSvc on the target node.
  • Verify network connectivity between cluster nodes.
  • For drain failures, check if VMs have anti-affinity rules or cannot migrate: Get-ClusterGroup | Where-Object OwnerNode -eq <node>.
  • For eviction, ensure the node is drained first: Suspend-ClusterNode -Name <node> -Drain.

RS-4009

Cluster dashboard query failed

Cause: The cluster dashboard could not retrieve cluster status information. The Failover Clustering feature may not be installed, the cluster service is stopped, or the server is not a member of a cluster.

Resolution:

  • Check if server is clustered: Get-Cluster -ErrorAction SilentlyContinue.
  • Verify the cluster service: Get-Service ClusSvc.
  • If not clustered, the cluster dashboard is not applicable.
  • If clustered, check cluster health: Get-ClusterNode | Select-Object Name, State.

VM Pipeline (RS-5xxx)

RS-5001

VHD download or copy failed

Cause: A VHD or VHDX file could not be downloaded from the file server or copied from the specified path. The source may be unreachable, the download timed out, the file may be locked, or there is insufficient disk space on the destination.

Resolution:

  • Verify source accessibility: Test-Path <source> or Test-NetConnection <server> -Port 443.
  • Check available disk space: Get-PSDrive <drive-letter>.
  • If downloading, check the file server configuration in defaults.json.
  • Retry the download; transient network issues may resolve on their own.

RS-5002

VM creation failed

Cause: The virtual machine could not be created in Hyper-V. The VM name may already exist, the specified path may be inaccessible, memory allocation may exceed host capacity, or the virtual switch does not exist.

Resolution:

  • Check for name conflicts: Get-VM -Name <name>.
  • Verify the VM path exists and has sufficient space.
  • Confirm available host memory: Get-VMHostNumaNode | Select-Object MemoryAvailable.
  • Verify the target virtual switch exists: Get-VMSwitch.

RS-5003

ISO download timeout

Cause: An ISO file download did not complete within the allowed time. The file server may be slow, the network connection may be unreliable, or the ISO file is very large and the timeout is too short.

Resolution:

  • Check connectivity to the file server.
  • Pre-download the ISO manually and place it in the expected directory.
  • Verify the download URL is correct in your configuration.
  • If on a slow network, consider copying the ISO from local media or a USB drive.

RS-5004

Offline VHD servicing failed

Cause: Offline modifications to a VHD (injecting drivers, applying updates, modifying the registry) failed. The VHD may not have mounted correctly, the image may be corrupted, or DISM operations encountered errors.

Resolution:

  • Verify the VHD mounts manually: Mount-VHD -Path <path> -ReadOnly.
  • Check DISM logs at C:\Windows\Logs\DISM\dism.log for detailed errors.
  • Ensure the VHD contains a supported Windows image (not Linux or a data disk).
  • Re-download or re-create the VHD if the image is corrupted.

RS-5005

VM checkpoint operation failed

Cause: A VM checkpoint (snapshot) could not be created, applied, or removed. The VM may be in a saved state, the storage location may be full, or the checkpoint tree is corrupted.

Resolution:

  • Check VM state: Get-VM <name> | Select-Object State.
  • Verify disk space at the checkpoint location: the checkpoint files can be large.
  • List existing checkpoints: Get-VMCheckpoint -VMName <name>.
  • If the checkpoint tree is corrupted, export the VM and re-import it to reset the tree.

RS-5006

VM export or import failed

Cause: A VM export or import operation failed. The destination path may be inaccessible, there may not be enough disk space, or the VM is in a state that prevents export (e.g., replicating). Import may fail if the VM GUID conflicts with an existing VM.

Resolution:

  • Ensure the export destination has enough free space (VM size + memory state).
  • Stop the VM or use a production checkpoint for a clean export.
  • For import conflicts, use Import-VM -Copy -GenerateNewId to create a new unique VM.
  • Check for locked files if a previous export was interrupted.

RS-5007

Host storage path not found

Cause: The configured host storage path for VM files, VHDs, or ISOs does not exist or is not accessible. The drive may not be mounted, the folder may not have been created, or it references a stale path.

Resolution:

  • Verify the path: Test-Path <path>.
  • Create the directory if needed: New-Item -ItemType Directory -Path <path>.
  • Update the storage path in RackStack configuration if the location has changed.
  • Ensure the drive is online: Get-Disk | Where-Object IsOffline -eq $true | Set-Disk -IsOffline $false.

RS-5008

Hyper-V Replica operation failed

Cause: A Hyper-V Replica operation (enable, test failover, planned failover, reverse, or remove replication) failed. The replica server may be unreachable, replication health may be in a warning/critical state, or the VM may be in an incompatible state for the requested operation.

Resolution:

  • Check replication health: Get-VMReplication -VMName <vm> | Select-Object Health, State.
  • Verify the replica server is reachable: Test-NetConnection -ComputerName <replica-server> -Port 80.
  • Resume replication if paused: Resume-VMReplication -VMName <vm>.
  • For test failover failures, ensure the test network is configured on the replica server.

RS-5009

VHD mount or creation failed

Cause: A VHD/VHDX file could not be mounted or created. The file may be corrupted, already mounted by another process, the target path may not exist, or there may be insufficient disk space for the requested size.

Resolution:

  • Check if the VHD is already mounted: Get-VHD -Path <path> -ErrorAction SilentlyContinue.
  • Verify the target folder exists and has sufficient space.
  • If corrupted, try Optimize-VHD -Path <path> -Mode Full.
  • Dismount any orphaned mounts: Dismount-VHD -Path <path>.

RS-5010

Offline VHD registry hive operation failed

Cause: A registry hive could not be loaded from or unloaded to a mounted VHD during offline customization. The hive file may be locked by another process, the VHD may not be properly mounted, or a previous operation left the hive in a locked state.

Resolution:

  • Check for orphaned hive loads: reg query HKLM\OFFLINE_SYSTEM (if it exists, the hive is still loaded).
  • Unload manually: reg unload HKLM\OFFLINE_SYSTEM.
  • If the VHD is still mounted, dismount it: Dismount-VHD -Path <path>.
  • Ensure no other processes are accessing the VHD (check Disk Management).

Storage / Cluster (RS-6xxx)

RS-6001

No iSCSI sessions found

Cause: There are no active iSCSI sessions on this server. The iSCSI initiator service may not be running, no targets have been connected, or existing sessions have been disconnected.

Resolution:

  • Check the iSCSI service: Get-Service MSiSCSI and start it if stopped.
  • List target portals: Get-IscsiTargetPortal.
  • Connect to a target: Connect-IscsiTarget -NodeAddress <iqn>.
  • Make sessions persistent so they survive reboots: Connect-IscsiTarget -NodeAddress <iqn> -IsPersistent $true.

RS-6002

Cluster validation failed

Cause: Failover Cluster validation reported critical errors. This is a prerequisite before creating or adding nodes to a cluster. Common failures include storage, networking, or system configuration mismatches between nodes.

Resolution:

  • Run validation: Test-Cluster -Node <node1>,<node2>.
  • Review the generated HTML report (default: C:\Users\<user>\AppData\Local\Temp).
  • Fix all errors and warnings; Microsoft Support requires clean validation for cluster support.
  • Common fixes: match NIC names across nodes, ensure shared storage is visible to all nodes, synchronize time.

RS-6003

Storage backend initialization failed

Cause: The configured storage backend (local path, SMB share, or iSCSI) could not be initialized. The path may not exist, credentials may be invalid, or the storage service is unavailable.

Resolution:

  • Verify the backend type and path in your RackStack configuration.
  • For SMB: test with Test-Path \\<server>\<share> and check credentials.
  • For iSCSI: verify sessions are connected (see RS-6001).
  • For local storage: ensure the drive is online and the path exists.

RS-6004

Disk initialization failed

Cause: A raw disk could not be initialized with a partition table. The disk may be read-only, in use by another process, or have a protective GPT header that needs to be cleared.

Resolution:

  • List disks: Get-Disk | Where-Object PartitionStyle -eq 'RAW'.
  • Initialize manually: Initialize-Disk -Number <n> -PartitionStyle GPT.
  • If the disk is read-only: Set-Disk -Number <n> -IsReadOnly $false.
  • Clear a disk completely (destroys data): Clear-Disk -Number <n> -RemoveData -Confirm:$false.

RS-6005

Cluster shared volume unavailable

Cause: A Cluster Shared Volume (CSV) is in a failed, offline, or maintenance state. This can occur after a node failure, storage path interruption, or CSV metadata corruption.

Resolution:

  • Check CSV status: Get-ClusterSharedVolume | Select-Object Name, State.
  • Resume a suspended CSV: Resume-ClusterResource <csv-name>.
  • Move the CSV owner to another node: Move-ClusterSharedVolume <csv-name> -Node <node>.
  • Verify underlying storage connectivity (iSCSI sessions, MPIO paths, physical disk health).

RS-6006

Disk operation failed

Cause: A disk operation (initialize, bring online/offline, clear) failed. The disk may be in use by another process, locked by a cluster, or have a read-only attribute set. Storage controller issues or failing hardware can also cause this error.

Resolution:

  • Check disk status: Get-Disk | Select-Object Number, FriendlyName, OperationalStatus, HealthStatus.
  • Clear read-only: Set-Disk -Number <n> -IsReadOnly $false.
  • Bring online: Set-Disk -Number <n> -IsOffline $false.
  • If the disk is clustered, remove it from the cluster first or manage it from the owner node.

RS-6007

Partition operation failed

Cause: A partition create, delete, extend, or shrink operation failed. The disk may not have enough free space, the partition may be in use, or the operation requires unmounting the volume first.

Resolution:

  • Check available space: Get-Partition -DiskNumber <n> | Select-Object PartitionNumber, Size.
  • Ensure the volume is not in use by stopping services that reference it.
  • For extend operations, verify contiguous unallocated space exists after the partition.
  • Use Resize-Partition -DiskNumber <n> -PartitionNumber <p> -Size <bytes> for precise sizing.

RS-6008

Disk cleanup operation failed

Cause: A disk cleanup operation (Disk Cleanup tool, component store cleanup, or shadow copy deletion) failed. The cleanmgr utility may not be installed (Server Core), the component store may be corrupted, or a VSS writer is in a failed state.

Resolution:

  • On Server Core, install the Desktop Experience feature or use DISM directly: DISM /Online /Cleanup-Image /StartComponentCleanup.
  • Check VSS writers: vssadmin list writers and look for failed or unstable writers.
  • For shadow copy deletion: vssadmin delete shadows /for=C: /oldest.
  • Run sfc /scannow if the component store is corrupted.

RS-6009

Storage backend detection failed

Cause: Automatic storage backend detection (S2D, FC, iSCSI, SMB3, NVMeoF, Local) failed. The required PowerShell modules may not be installed, the storage service may be unavailable, or the server does not have any storage backends configured.

Resolution:

  • Check available storage: Get-Disk | Select-Object Number, FriendlyName, BusType, Size.
  • For S2D: verify Failover Clustering and Storage Spaces Direct are enabled.
  • For FC: check HBA drivers and Get-InitiatorPort.
  • Override automatic detection in defaults.json: set StorageBackendType to iSCSI, FC, S2D, SMB3, NVMeoF, or Local.

RS-6010

Disk rescan operation failed

Cause: A disk rescan (typically triggered during FC or iSCSI storage operations) could not complete. The storage controller driver may be unresponsive, the FC HBA may have lost connectivity, or the storage subsystem service is in a degraded state.

Resolution:

  • Rescan manually: Update-HostStorageCache or Get-Disk | Update-Disk.
  • Check storage connectivity (FC link state, iSCSI sessions).
  • Restart the storage subsystem if needed: Restart-Service ShellHWDetection.
  • Open Disk Management (diskmgmt.msc) and use Action > Rescan Disks.

RS-6011

Volume format operation failed

Cause: A volume could not be formatted with the requested file system (NTFS, ReFS). The partition may be in use, the disk may be read-only, or there is insufficient space for the file system metadata.

Resolution:

  • Check if the volume is in use: close any open Explorer windows or processes accessing the drive.
  • Verify disk is not read-only: Get-Disk <number> | Select-Object IsReadOnly.
  • Clear read-only: Set-Disk <number> -IsReadOnly $false.
  • Format manually: Format-Volume -DriveLetter <letter> -FileSystem NTFS -Confirm:$false.

Configuration / Export (RS-7xxx)

RS-7001

Configuration export failed

Cause: RackStack could not export the current server configuration to a file. The output path may be inaccessible, the disk may be full, or an error occurred while gathering configuration data from a Windows component.

Resolution:

  • Verify the export path exists and is writable.
  • Check available disk space on the target drive.
  • Try exporting to a different location (e.g., C:\Temp).
  • Review the error details for which specific configuration section failed.

RS-7002

DC promotion failed

Cause: Active Directory Domain Controller promotion failed. Common causes include DNS misconfiguration, missing AD DS role, insufficient credentials, or a prerequisite check failure. The DSRM password may also not meet complexity requirements.

Resolution:

  • Install the AD DS role first: Install-WindowsFeature AD-Domain-Services -IncludeManagementTools.
  • Ensure DNS is properly configured and the server can resolve the forest/domain name.
  • Use Enterprise Admin or Domain Admin credentials for promotion.
  • Check the AD DS prerequisite logs: C:\Windows\debug\dcpromo.log and C:\Windows\debug\adprep.

RS-7003

Server role template apply failed

Cause: A server role template could not be fully applied. One or more features in the template failed to install, a configuration step was rejected, or the template references features not available on this OS edition.

Resolution:

  • Check which features failed: review the error details for specific feature names.
  • Verify the template is compatible with your Windows Server version and edition.
  • Install failed features individually to isolate the problem: Install-WindowsFeature <name>.
  • A reboot may be required between certain feature installations.

RS-7004

Scheduled task creation failed

Cause: A Windows scheduled task could not be created. The task name may conflict with an existing task, the action or trigger definition may be invalid, or the service account lacks "Log on as a batch job" rights.

Resolution:

  • Check for conflicts: Get-ScheduledTask -TaskName '<name>'.
  • Verify the service account: whoami and ensure it has the appropriate permissions.
  • Grant "Log on as a batch job" via Local Security Policy (secpol.msc) if needed.
  • Create manually: Register-ScheduledTask -TaskName '<name>' -Action <action> -Trigger <trigger>.

RS-7005

Hyper-V Replica configuration failed

Cause: Hyper-V Replica could not be configured between the primary and replica servers. The Hyper-V Replica Broker may not be configured (for clustered environments), firewall rules may block replication traffic, or certificates are not properly configured for HTTPS replication.

Resolution:

  • Enable replication on the replica server: Set-VMReplicationServer -ReplicationEnabled $true -AllowedAuthenticationType Kerberos -ReplicationAllowedFromAnyServer $true.
  • Open firewall: Enable-NetFirewallRule -DisplayName 'Hyper-V Replica HTTP*' (port 80) or HTTPS (port 443).
  • For clusters, configure a Hyper-V Replica Broker role in Failover Cluster Manager.
  • Ensure both servers can resolve each other's FQDNs.

RS-7006

Scheduled task operation failed

Cause: A scheduled task could not be created, modified, imported, or registered. The task XML may be malformed, the specified user account may not have "Log on as a batch job" rights, or the Task Scheduler service is not running.

Resolution:

  • Check the Task Scheduler service: Get-Service Schedule.
  • Validate task XML before import: open in a text editor and verify XML syntax.
  • Grant batch logon rights: Local Security Policy → User Rights Assignment → "Log on as a batch job".
  • For import failures, try creating the task interactively first to identify the specific error.
  • Check the task path exists: Get-ScheduledTask -TaskPath <path> (create parent folders if needed).

RS-7007

Active Directory prerequisite check failed

Cause: An Active Directory operation (DC promotion, replication monitoring, AD module loading) could not proceed because prerequisites were not met. The RSAT AD tools may not be installed, the server may not be domain-joined, or DNS is not configured correctly for AD operations.

Resolution:

  • Install AD management tools: Install-WindowsFeature RSAT-AD-Tools, RSAT-DNS-Server.
  • Verify domain membership: (Get-CimInstance Win32_ComputerSystem).PartOfDomain.
  • Check DNS configuration points to a domain controller: Resolve-DnsName <domain>.
  • For DC promotion, ensure a static IP is configured (not DHCP).

Agent / External (RS-8xxx)

RS-8001

Agent installer not found

Cause: The agent installer package could not be found at the configured path or URL. The file may have been moved, the file server path may be incorrect, or the installer filename does not match what RackStack expects.

Resolution:

  • Verify the installer path in your defaults.json configuration.
  • Check that the file exists at the specified location.
  • If using a file server, confirm the server is accessible and the share permissions allow read access.
  • Re-download the installer and place it in the expected location.

RS-8002

File server unreachable

Cause: The configured file server for downloads (VHDs, ISOs, agents) is not responding. The server may be down, the network path may be blocked, or the URL/UNC path is misconfigured.

Resolution:

  • Test connectivity: Test-NetConnection -ComputerName <server> -Port <port>.
  • For UNC paths: Test-Path \\<server>\<share>.
  • Verify the file server URL or path in defaults.json.
  • Check DNS resolution: Resolve-DnsName <server-hostname>.

RS-8003

Agent installation failed

Cause: The agent installer was found and executed but the installation did not succeed. The installer may require specific prerequisites, the system may need a reboot first, or a previous installation is interfering.

Resolution:

  • Check the agent installer's own log files for detailed error messages.
  • Uninstall any previous version of the agent before retrying.
  • Verify prerequisites (e.g., .NET Framework version, Visual C++ redistributables).
  • Run the installer manually in an elevated shell to see interactive error messages.

RS-8004

Download failed after max retries

Cause: A file download was attempted multiple times but failed on every retry. The source server may be experiencing intermittent failures, the network may be unstable, or the file may no longer exist at the specified URL.

Resolution:

  • Test the download URL directly in a browser or with Invoke-WebRequest -Uri <url> -OutFile test.tmp.
  • Check network stability: Test-NetConnection -ComputerName <server>.
  • Verify the file still exists at the source location.
  • If the server requires authentication, ensure credentials are configured correctly in defaults.json.

Home

Configuration

Guides

Runbooks

Reference

GitHub Repo | Releases

Clone this wiki locally