winfig/TROUBLESHOOTING.md

Troubleshooting Guide

This guide covers common issues and their solutions when using winfig.

Table of Contents

• PowerShell Issues
• Oh-My-Posh Issues
• Windows Terminal Issues
• Git Issues
• Scoop Issues
• Font and Display Issues
• Performance Issues
• General Issues

PowerShell Issues

Profile Not Loading

Symptom: PowerShell starts but custom functions and theme are not available.

Solutions:

1. Check if profile exists:

   Test-Path $PROFILE
   

2. Check execution policy:

   Get-ExecutionPolicy
   # Should be RemoteSigned or Unrestricted
   

3. Set execution policy if needed:

   Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
   

4. Check for errors in profile:

   & $PROFILE
   # Look for error messages
   

Module Import Errors

Symptom: Errors about missing modules (posh-git, Terminal-Icons, PSFzf).

Solution:

Install missing modules:

Install-Module posh-git -Scope CurrentUser -Force
Install-Module Terminal-Icons -Scope CurrentUser -Force
Install-Module PSFzf -Scope CurrentUser -Force

Slow Startup

Symptom: PowerShell takes a long time to start.

Solutions:

1. Check which modules are slow to load:

   Measure-Command { & $PROFILE }
   

2. Disable unused modules in user_profile.ps1

3. Ensure lazy loading is working:

   # Check if background job completed
   Get-Job
   

Functions Not Working

Symptom: Custom functions like gs, gp, .. don't work.

Solutions:

1. Reload profile:

   . $PROFILE
   

2. Check if function exists:

   Get-Command gs
   

3. Check for conflicts:

   Get-Alias gs -ErrorAction SilentlyContinue
   

Oh-My-Posh Issues

Theme Not Displaying

Symptom: Prompt is plain text, no colors or icons.

Solutions:

1. Check if Oh-My-Posh is installed:

   Get-Command oh-my-posh
   

2. Install Oh-My-Posh:

   scoop install oh-my-posh
   

3. Verify theme file exists:

   Test-Path (Join-Path (Split-Path $PROFILE) "m1ng.omp.json")
   

Icons Not Showing (Boxes/Question Marks)

Symptom: Squares, boxes, or question marks instead of icons.

Solutions:

1. Install a Nerd Font:

   scoop bucket add nerd-fonts
   scoop install CascadiaCode-NF
   

2. Set font in Windows Terminal:

   • Open Settings (Ctrl+,)
   • Go to Appearance
   • Set Font face to "CaskaydiaCove Nerd Font" or another Nerd Font

3. Restart Windows Terminal

Theme Performance Issues

Symptom: Prompt is slow, especially in Git repositories.

Solutions:

1. Disable Git status fetching in theme:

   • Edit m1ng.omp.json
   • Set fetch_status: false in git segment

2. Use simpler theme:

   oh-my-posh init pwsh --config "$env:POSH_THEMES_PATH\minimal.omp.json" | Invoke-Expression
   

Windows Terminal Issues

Settings Not Applied

Symptom: Windows Terminal doesn't show custom settings.

Solutions:

1. Verify settings location:

   $settingsPath = "$env:LOCALAPPDATA\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\LocalState\settings.json"
   Test-Path $settingsPath
   

2. Open settings in editor:

   • Press Ctrl+Shift+, (opens JSON file)
   • Verify settings are correct

3. Check for JSON errors:

   • Look for syntax errors in settings.json
   • Use a JSON validator

4. Reset to defaults:

   • Rename settings.json
   • Restart Windows Terminal (creates new defaults)
   • Re-apply winfig settings

Keybindings Not Working

Symptom: Custom keybindings don't work.

Solutions:

1. Check for conflicts:

   • Open Settings → Actions
   • Look for duplicate keybindings

2. Verify in settings.json:

   • Check actions array
   • Ensure no syntax errors

3. Try different key combination

Font Not Changing

Symptom: Terminal doesn't use Nerd Font.

Solutions:

1. Install font system-wide:

   # Download and install font file
   # Or use Scoop
   scoop install CascadiaCode-NF
   

2. Set in PowerShell profile settings:

   • Settings → Profiles → PowerShell → Appearance
   • Set Font face manually

3. Restart Windows Terminal

Git Issues

Config Not Applied

Symptom: Git aliases don't work.

Solutions:

1. Verify config location:

   git config --list --show-origin
   

2. Manually copy config:

   Copy-Item git\.gitconfig ~\.gitconfig -Force
   

3. Set user info:

   git config --global user.name "Your Name"
   git config --global user.email "your@email.com"
   

Aliases Not Working

Symptom: Git aliases like git lg, git sync don't work.

Solutions:

1. Check if alias exists:

   git config --get-regexp alias
   

2. Test alias:

   git config alias.lg
   

3. Manually add alias:

   git config --global alias.lg "log --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"
   

Line Ending Issues

Symptom: Git shows all files as modified (^M characters).

Solutions:

1. Configure line endings:

   git config --global core.autocrlf true
   

2. Refresh repository:

   git rm --cached -r .
   git reset --hard
   

Scoop Issues

Scoop Not Found

Symptom: scoop command not recognized.

Solutions:

1. Install Scoop:

   Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
   irm get.scoop.sh | iex
   

2. Add to PATH:

   $env:PATH += ";$env:USERPROFILE\scoop\shims"
   

3. Restart PowerShell

Package Installation Fails

Symptom: scoop install <package> fails.

Solutions:

1. Update Scoop:

   scoop update
   

2. Check for conflicts:

   scoop list
   

3. Clear cache:

   scoop cache rm *
   

4. Try different bucket:

   scoop bucket add extras
   scoop search <package>
   

Slow Downloads

Symptom: Package downloads are slow.

Solutions:

1. Enable aria2:

   scoop install aria2
   scoop config aria2-enabled true
   

2. Increase connections:

   scoop config aria2-max-connection-per-server 16
   scoop config aria2-split 16
   

Font and Display Issues

Icons Show as Boxes

Symptom: Icons appear as boxes or question marks.

Solutions:

1. Install Nerd Font:

   scoop bucket add nerd-fonts
   scoop install CascadiaCode-NF
   

2. Set font in all profiles:

   • Windows Terminal: Settings → Profiles → Defaults → Appearance
   • Set Font face to Nerd Font

3. Verify font is installed:

   • Windows Settings → Fonts
   • Search for "Cascadia" or your chosen font

Colors Look Wrong

Symptom: Colors are incorrect or washed out.

Solutions:

1. Enable TrueColor:

   • Windows Terminal Settings → Rendering
   • Disable "Use legacy console"

2. Check color scheme:

   • Settings → Profiles → Color scheme
   • Try different scheme (One Half Dark, Dracula)

3. Update terminal:

   scoop update windows-terminal
   

Blurry or Pixelated

Symptom: Text appears blurry or pixelated.

Solutions:

1. Adjust antialiasing:

   • Settings → Rendering
   • Try different antialiasing modes (ClearType, Grayscale)

2. Check DPI scaling:

   • Windows Settings → Display
   • Ensure DPI scaling is appropriate

3. Disable Acrylic:

   • Settings → Appearance
   • Turn off "Acrylic material"

Performance Issues

Slow Terminal Startup

Symptom: Terminal takes long to open.

Solutions:

1. Disable unnecessary startup tasks:

   • Edit user_profile.ps1
   • Comment out unused module imports

2. Use lazy loading:

   • Already implemented in winfig profile

3. Clear temp files:

   Remove-Item $env:TEMP\* -Recurse -Force -ErrorAction SilentlyContinue
   

Sluggish Git Operations

Symptom: Git commands are slow.

Solutions:

1. Disable Oh-My-Posh git status:

   • Edit m1ng.omp.json
   • Set fetch_status: false

2. Configure Git to use FSCache:

   git config --global core.fscache true
   git config --global core.preloadindex true
   

3. Exclude antivirus scanning:

   • Add Git installation directory to antivirus exclusions

High Memory Usage

Symptom: PowerShell uses excessive memory.

Solutions:

1. Check for module leaks:

   Get-Process pwsh | Select-Object -Property *
   

2. Restart PowerShell regularly

3. Limit history size:

   Set-PSReadLineOption -MaximumHistoryCount 1000
   

General Issues

Permission Errors

Symptom: "Access denied" or permission errors.

Solutions:

1. Run as Administrator:

   • Right-click Windows Terminal
   • Select "Run as administrator"

2. Use sudo:

   scoop install sudo
   sudo <command>
   

3. Check file permissions:

   Get-Acl $PROFILE
   

Profile Conflicts

Symptom: Multiple profiles causing conflicts.

Solutions:

1. Check profile locations:

   $PROFILE | Format-List * -Force
   

2. Use correct profile:

   • CurrentUserCurrentHost (recommended)
   • Edit only this profile

3. Remove conflicting profiles:

   Remove-Item $PROFILE.CurrentUserAllHosts -ErrorAction SilentlyContinue
   

Setup Script Fails

Symptom: setup.ps1 fails with errors.

Solutions:

1. Run with execution policy:

   Set-ExecutionPolicy Bypass -Scope Process
   .\setup.ps1
   

2. Check error message and fix specific issue

3. Use selective setup:

   .\setup.ps1 -SkipScoop  # Skip problematic component
   

4. Manual setup:

   • Copy files manually from each directory
   • Follow README in each subdirectory

Backup/Restore Issues

Symptom: Backup or restore fails.

Solutions:

1. Check disk space:

   Get-PSDrive C
   

2. Run with administrator privileges

3. Check paths:

   Test-Path .\backups
   

4. Use full paths:

   .\backup.ps1
   # Instead of relative paths
   

Getting More Help

If you continue to experience issues:

1. Check Documentation:

   • Read component-specific READMEs
   • Review configuration comments

2. Enable Verbose Output:

   $VerbosePreference = "Continue"
   .\setup.ps1 -Verbose
   

3. Check Logs:

   • PowerShell: $error[0] | Format-List * -Force
   • Scoop: scoop cache show

4. Create an Issue:

   • GitHub: winfig issues
   • Include error messages and system info

5. Community Support:

   • Windows Terminal discussions
   • Oh-My-Posh GitHub
   • Scoop community

System Information

To gather system information for troubleshooting:

# PowerShell version
$PSVersionTable

# Windows version
Get-ComputerInfo | Select-Object WindowsVersion, OsArchitecture

# Installed modules
Get-Module -ListAvailable | Where-Object Name -in 'posh-git','Terminal-Icons','PSFzf'

# Scoop status
scoop status

# Git version
git --version

# Oh-My-Posh version
oh-my-posh version

Include this information when reporting issues.