# Troubleshooting Symptom → cause → the exact command that fixes it. Start here when something went wrong. If your problem is not listed, produce a diagnostics bundle and [open an issue](https://github.com/paulmann/Print-Spooler-Queue-Cleanup/issues) — see the last section. --- ## Cleanup failures ### "The Spooler will not stop" / stuck in `STOP_PENDING` **Cause.** Almost always `PrintNotify` ("Printer Extensions and Notifications") or a hung `splwow64.exe` holding a handle. This is the single most common reason the classic `net stop spooler` fails. **Fix.** ```powershell .\Clear-PrintSpoolerQueue.ps1 -Repair -Force -Backup ``` `-Repair` stops `PrintWorkflowUserSvc_*`, `Fax` and `PrintNotify` **before** the Spooler. If it still hangs, `Service.ForceStopFallback` (default `$true`) escalates to terminating the service process — safe for the Spooler, because the SCM treats an exited service process as stopped. **Confirm the diagnosis** by reading `serviceTrace[]` in the report, which records every transition with its from/to state and duration: ```powershell $run = .\Clear-PrintSpoolerQueue.ps1 -Repair -Force -Backup -PassThru $run.Results[0].ServiceTrace | Format-Table Service, Action, From, To, Success, Note ``` --- ### Files come straight back after the cleanup **Cause.** A driver or port monitor is re-submitting them, or a client keeps resending. The report flags this as `ResurrectedFiles > 0`. **Fix.** ```powershell .\Clear-PrintSpoolerQueue.ps1 -Diagnostic -ExportFormat Html -ExportPath C:\Temp ``` Look at the **Driver** and **Port** columns of the printer table, and at the driver list. Then: ```powershell .\Clear-PrintSpoolerQueue.ps1 -Repair -PurgeDriverStore -Force -Backup ``` `-PurgeDriverStore` removes driver packages that **no** printer references — it cannot remove a driver that is in use. If the offending driver is still attached to a printer, remove or replace that printer's driver first. --- ### "Access is denied" on some files only **Cause.** The file is held open by `spoolsv.exe`. **Behaviour.** The tool retries with exponential backoff (500 ms → 1 s → 2 s) and reports the remainder as `FilesLocked` with the exact per-file error. A locked file never aborts the run. **Fix.** Usually none is needed — the exit code will be `1` (PartialSuccess) and the queue is unblocked. To push harder: ```powershell .\Clear-PrintSpoolerQueue.ps1 -Force -Backup -RetryCount 6 -RetryDelayMs 1000 -SettleSeconds 5 ``` A longer `-SettleSeconds` gives the service more time to release handles after the stop, which is the most effective knob. --- ### Exit code 2 with "Refusing to operate on…" **Cause.** One of the four safety guards fired. The message names the guard. | Message | Meaning | |---|---| | `Leaf 'X' must be 'PRINTERS'` | The resolved directory is not a spool directory | | `must live under a 'spool' folder` | A corrupt `DefaultSpoolDirectory`, e.g. `C:\Users\PRINTERS` | | `not rooted at a Windows drive letter` | A relative or POSIX-style path | | `UNC spool directories are refused` | Clean the file server on the file server | | `path is too shallow` | A truncated registry value | | `equals a protected system root` | `C:\Windows` and friends | **Fix.** Inspect the registry override: ```powershell Get-ItemProperty 'HKLM:\SYSTEM\CurrentControlSet\Control\Print\Printers' -Name DefaultSpoolDirectory ``` If it is genuinely corrupt, let the tool reset it: ```powershell .\Clear-PrintSpoolerQueue.ps1 -Repair -ResetSpoolDirectory -Force ``` If the host legitimately uses a non-standard layout, pass it explicitly (still guarded): ```powershell .\Clear-PrintSpoolerQueue.ps1 -SpoolDirectory 'D:\Print\spool\PRINTERS' -Force -Backup ``` **Never** work around a guard by editing the constant. The guard fired because something upstream is wrong, and that something is worth knowing about. --- ### Exit code 2 with "…spool files found (guard limit 100000)" **Cause.** The volume guard. Either a queue has genuinely exploded, or the directory resolved somewhere unexpected. **Fix.** `-Diagnostic` first. Check `SpoolDirectory.Path` and the per-extension breakdown. If the path is wrong, this is the registry case above. If the path is right and there really are 100 000 files, you have an incident that needs a human, not a script. --- ## Remote execution ### All remote targets fail with a timeout **Cause.** WinRM is not configured, or TCP 5985/5986 is blocked. **Fix.** ```powershell # On each target Enable-PSRemoting -Force # For workgroup (non-domain) machines, on BOTH sides Set-Item WSMan:\localhost\Client\TrustedHosts -Value "10.0.0.*" -Force # Firewall Get-NetFirewallRule -DisplayGroup "Windows Remote Management" | Enable-NetFirewallRule ``` Use `-PreFlightProbe` (on by default) to get the exact per-host reason in about a second each, instead of a 40-second timeout per host: ```powershell $run = .\Clear-PrintSpoolerQueue.ps1 -ComputerName (Get-Content .\hosts.txt) -Force -PassThru $run.Results | Where-Object Status -eq 'Failed' | Format-Table ComputerName, Errors -Wrap ``` --- ### Some hosts work, others do not Mixed PowerShell versions are **fine** — the payload only uses cmdlets available in Windows PowerShell 5.1, so it runs on an old Server 2012 R2 target and on PowerShell 7.6 alike. Mixed *credentials* are not. Either the caller must be a local administrator on every target, or you must pass `-Credential`: ```powershell $cred = Get-Credential .\Clear-PrintSpoolerQueue.ps1 -ComputerName $hosts -Credential $cred -Force -Backup ``` For HTTPS-only environments add `-UseSsl`. --- ### `-ThrottleLimit` seems to do nothing `-ThrottleLimit > 1` uses `ForEach-Object -Parallel`, which needs **PowerShell 7**. On Windows PowerShell 5.1 the tool automatically falls back to a runspace pool with the same throttling, so it still parallelises — but check which engine you are on: ```powershell $PSVersionTable.PSVersion ``` If you are being launched by the `.bat`, it prefers `pwsh.exe` when present; force it with `/PS7`. --- ## Selection filters ### `-PrinterName` matches nothing although jobs are visible **Cause.** When the Spooler is hung it cannot answer WMI, so the inventory is built from `.SHD` headers, where the printer name is best-effort. Jobs with no readable metadata cannot be matched by name and are **deliberately not selected** — the run reports this in its warnings. **Confirm.** ```powershell .\Clear-PrintSpoolerQueue.ps1 -Diagnostic | Select-Object -ExpandProperty Results | Select-Object -ExpandProperty Jobs | Format-Table JobId, PrinterName, Source ``` `Source` is `WMI` (authoritative), `WMI+SHD` (correlated) or `SHD` (best-effort). **Fix.** Filter by `-JobId` instead — the id is derived from the `.SHD` file name and is always available — or use `-OlderThan`, which relies on file timestamps rather than metadata. Or drop the filter when the whole queue must go. --- ### Everything was deleted although I passed a filter Check the **execution plan** the tool prints before it asks for confirmation: ``` Selection : jobs matching: printers like 'HP*'; older than 2h ``` If it says `ALL spool files (*.SPL, *.SHD)`, no filter reached the tool. The usual cause is a parameter typo, or passing the filter positionally where it bound to `-ComputerName`. `-WhatIf` shows the same plan with zero risk: ```powershell .\Clear-PrintSpoolerQueue.ps1 -PrinterName "HP*" -WhatIf ``` --- ## Logging and output ### The log file is missing The resolved log path is printed in the summary and recorded in the report. If the script lives somewhere read-only, the tool falls back automatically: `-LogPath` → `%ProgramData%\PrintSpoolerCleanup\Logs` → `%LocalAppData%\PrintSpoolerCleanup\Logs` → `