Skip to content

troubleshooting.md

Latest commit

 

History

History
193 lines (128 loc) · 10.2 KB

troubleshooting.md

File metadata and controls

193 lines (128 loc) · 10.2 KB
Raw

PowerShell IT Support Toolkit — Troubleshooting Guide

1. Overview

This troubleshooting guide is designed to help IT Support Engineers quickly diagnose and resolve problems encountered while using the PowerShell IT Support Toolkit.

It is important to distinguish between troubleshooting the toolkit (e.g., a script fails to execute or a module fails to load) and troubleshooting the system (e.g., the network script runs perfectly, but reports that DNS is unreachable). This guide focuses entirely on the former—ensuring the toolkit itself operates reliably.

2. General Troubleshooting Workflow

When a toolkit script fails, follow this general diagnostic workflow:

  1. Confirm the project files exist: Verify that the project was extracted correctly and that the script you are trying to run exists (e.g., Test-Path .\scripts\IT-Toolkit.ps1).
  2. Confirm PowerShell environment: Verify you are running Windows PowerShell 5.1 or PowerShell 7+ by typing $PSVersionTable.
  3. Run the script directly: If a script fails from the main menu, try running the backend script directly from the console to isolate the error message.
  4. Review toolkit logs: Check logs\toolkit.log for any internal toolkit errors.
  5. Check Administrator privileges: Certain operations (like restarting services or reading security logs) will fail with "Access Denied" if you are not elevated.
  6. Escalate with logs: If the issue persists, gather the exact error message and the toolkit log before reporting a bug.

3. Toolkit Does Not Start

If the main interactive menu orchestrator (IT-Toolkit.ps1) fails to launch:

Incorrect Script Path

  • Symptom: The term '.\scripts\IT-Toolkit.ps1' is not recognized...
  • Fix: You are in the wrong working directory. Ensure your console is situated at the root of the project directory before executing .\scripts\IT-Toolkit.ps1.

Execution Policy Restrictions

  • Symptom: IT-Toolkit.ps1 cannot be loaded because running scripts is disabled on this system.
  • Fix: Restart the toolkit using process-level bypass instead of attempting to run it natively in a restricted console: 
    powershell.exe -ExecutionPolicy Bypass -File ".\scripts\IT-Toolkit.ps1"

4. Common Module/Import Problems

The toolkit relies on essential internal shared modules.

Missing Module Files

  • Symptom: Red error stating The specified module '...\scripts\common\Common.psm1' was not loaded...
  • Check: The toolkit dynamically resolves these paths relative to the executing script. If the common\ directory was deleted or the scripts were moved outside of the intended directory structure, they will fail.
  • Fix: Restore the original project directory structure. The orchestrator must be in scripts\ and the modules must be in scripts\common\.

Missing Exported Functions

  • Symptom: The term 'Write-ToolkitLog' is not recognized as the name of a cmdlet...
  • Fix: The Logger.psm1 or Common.psm1 module failed to load. Ensure you have not modified these .psm1 files and accidentally removed the Export-ModuleMember declarations.

5. Menu Problems

If the main menu in IT-Toolkit.ps1 is malfunctioning:

Backend Script Not Found

  • Symptom: Selecting a menu option returns a path error or immediately drops back to the prompt.
  • Fix: The orchestrator maps menu options to specific backend scripts (e.g., Option 2 maps to scripts\system\Get-Processes.ps1). If that specific .ps1 file was renamed or deleted, the child process will fail.

Menu Loop Drops Out

  • Symptom: After executing a valid option, the script terminates instead of returning to the menu.
  • Fix: Ensure $ErrorActionPreference = 'Stop' hasn't caused an unhandled terminating error inside the orchestrator. Check logs\toolkit.log for details.

6. Script Execution Failures

Child scripts are executed in an isolated PowerShell process by the orchestrator (via pwsh.exe or powershell.exe -File).

Direct Execution vs Menu Execution

If a backend script (e.g., Get-DiskSpaceReport.ps1) fails when selected from the menu:

  1. Navigate to the project root.
  2. Execute the script directly: .\scripts\storage\Get-DiskSpaceReport.ps1
  3. If it succeeds directly but fails in the menu, the issue lies in child-process execution parameters or $LASTEXITCODE mapping in IT-Toolkit.ps1.
  4. If it fails directly, the issue lies within the script itself. Look for the standard [ErrorType] Error Message formatted output provided by the global catch block.

7. Common Script Categories

System Information & Running Processes

  • Symptom: Get-Processes.ps1 crashes when hitting a protected system process.
  • Fix: The script should natively handle inaccessible process properties via SilentlyContinue or internal try/catch blocks. If it terminates, ensure you haven't manually modified the script to remove these resiliency mechanisms.

Services

  • Symptom: Restart-ServiceSafely.ps1 returns Access Denied.
  • Fix: Restarting Windows services requires the console to be elevated. Run PowerShell as Administrator.

8. Permissions and Administrator Requirements

  • Read-only scripts: Scripts like Get-IPConfiguration.ps1 or Get-SystemInfo.ps1 should run as a standard user.
  • Administrative scripts: Scripts that manipulate state (Disable-User.ps1, Stop-Service.ps1) must be run in an elevated session.
  • Partial Failures: If an operation like Backup-FolderData.ps1 succeeds on some files but fails on others, it is usually due to locked files or standard permission constraints. This is expected system behavior, not a script bug.

9. Network Diagnostics Troubleshooting

The scripts\networking\ directory contains wrappers around native Windows tools.

  • Ping / Tracert Failures: If Test-Ping.ps1 or TraceRoute.ps1 fails, check if the failure is a network timeout (the system is offline) or a syntax failure (invalid hostname/IP).
  • Native Tool Exit Codes: The orchestrator monitors $LASTEXITCODE. If a native tool like ping.exe fails to find the host, it returns a non-zero exit code. The toolkit is designed to catch this and report a failure.

10. Event Logs Troubleshooting

  • Symptom: Get-SystemErrors.ps1 returns no data or fails with an access error.
  • Fix: Certain event logs (specifically Security) restrict read access to Administrators. Run elevated. If you still receive no data, verify that the specified log name and Event IDs actually exist on the target machine.

11. Storage and Temporary Cleanup Troubleshooting

The Clear-TempFiles.ps1 script performs potentially destructive actions.

  • Symptom: Files are skipped or the script reports Partial success.
  • Fix: This is intended behavior. The script safely bypasses locked files currently in use by the OS or running applications using -ErrorAction SilentlyContinue. Do not attempt to force-delete these files, as it can destabilize the system.
  • Symptom: Custom path deletion fails.
  • Fix: Ensure the custom path is absolute and verified by Test-Path. The script is designed to reject invalid or dangerous target paths to prevent accidental system deletion.

12. Export/Report Problems

Many diagnostic scripts support an -ExportPath parameter.

  • Symptom: The script runs successfully, but no JSON report is generated.
  • Fix: Verify the target directory exists. Export-ToolkitReport requires a valid path. If you specify .\output\report.json, ensure the output\ folder actually exists in the project root.
  • Symptom: Access Denied when exporting.
  • Fix: You specified an export path in a protected directory (e.g., C:\Windows\System32\). Export to the project's native output\ folder or a standard user directory like ~\Documents\.

13. Logging and Error Messages

The toolkit automatically logs errors via Write-ToolkitLog from Logger.psm1.

  • Log Location: By default, logs are written to logs\toolkit.log relative to the project root.
  • Log Failures: If the logger cannot write to toolkit.log (due to permissions or file locks), it will safely fall back to printing a standard Write-Warning to the console, ensuring the main script does not crash simply because logging failed.

14. PowerShell Syntax and Script Validation

If you modify a toolkit script and it immediately crashes upon execution:

  • Symptom: Unexpected token... or Missing closing '}'...
  • Fix: Before running, you can safely validate the script's syntax using the PowerShell parser: 
    $errors = $null
[System.Management.Automation.Language.Parser]::ParseFile(".\scripts\system\Get-Processes.ps1", [ref]$null, [ref]$errors)
$errors
    If $errors is empty, the syntax is valid.

15. Troubleshooting Checklist

Before escalating a toolkit issue, verify the following:

  • You are running Windows PowerShell 5.1 or PowerShell 7+.
  • You are launching the toolkit from its root directory.
  • The scripts\ and scripts\common\ directories exist.
  • You have bypassed the execution policy for the current process if required.
  • You are running as Administrator (if the task modifies system state).
  • The backend script runs successfully on its own, outside of the menu.
  • You have checked logs\toolkit.log for backend errors.

16. Reporting a Bug

If you have isolated an issue that indicates a bug in the toolkit itself, please gather the following information before filing a report:

  • Script Name: (e.g., IT-Toolkit.ps1 or Get-Processes.ps1)
  • PowerShell Version: (Output of $PSVersionTable.PSVersion)
  • Windows Version: (e.g., Windows 10 22H2)
  • Execution Method: (Did it fail from the main menu, or direct execution?)
  • Exact Command Used: (e.g., .\scripts\system\Get-Processes.ps1 -ExportPath .\test.json)
  • Exact Error Message: (Copy the exact text)
  • Expected Behavior: (What should have happened)
  • Actual Behavior: (What actually happened)
  • Reproducibility: (Does it happen every time?)

SECURITY NOTE: When submitting logs or error output, ensure you remove any sensitive network information, internal IP addresses, or proprietary system names before sharing.