Medios-Macina/docs/BOOTSTRAP_TROUBLESHOOTING.md

Bootstrap Installation Troubleshooting Guide

Problem on "Other Computer"

When running bootstrap.py on another machine, the installation completes successfully with messages about creating mm.ps1 and mm.bat, but the mm command is not recognized when executed.

Root Cause: Windows terminal sessions cache the PATH environment variable. When registry changes are made, existing terminal sessions don't automatically reload the new PATH. The shim files are created correctly, but they're not discoverable until PATH is reloaded.

Solution

Option 1: Restart Terminal (Easiest)

Simply close and reopen your terminal window or PowerShell session. Windows will automatically load the updated PATH from the registry.

# Close the current terminal
# Then open a new PowerShell or CMD window
mm --help

Option 2: Reload PATH in Current Session (Manual)

If you don't want to restart, you can reload the PATH in your current PowerShell session:

$env:PATH = [Environment]::GetEnvironmentVariable('PATH', 'User') + ';' + [Environment]::GetEnvironmentVariable('PATH', 'Machine')
mm --help

Note: The bootstrap installation automatically attempts this, but it may not work if PowerShell was launched with a restricted execution policy.

Option 3: Manual PATH Reload (PowerShell)

$env:Path = [Environment]::GetEnvironmentVariable('PATH', 'User') + ';' + [Environment]::GetEnvironmentVariable('PATH', 'Machine')
mm --help

Diagnostic Command

To verify the installation and troubleshoot issues:

python scripts/bootstrap.py --check-install

This will check:

• ✓ Shim files exist (mm.ps1 and mm.bat)
• ✓ Shim files have valid content
• ✓ PATH environment variable is configured
• ✓ Registry PATH was updated
• ✓ Test if mm command is accessible

Example Output

Checking 'mm' command installation...

Checking for shim files:
  mm.ps1: ✓ (C:\Users\Admin\bin\mm.ps1)
  mm.bat: ✓ (C:\Users\Admin\bin\mm.bat)

Checking PATH environment variable:
  C:\Users\Admin\bin in current session PATH: ✓
  C:\Users\Admin\bin in registry PATH: ✓

Testing 'mm' command...
  ✗ 'mm' command not found in PATH
     Shims exist but command is not accessible via PATH

Attempting to call shim directly...
  ✓ Direct shim call works!
     The shim files are valid and functional.

⚠️ 'mm' is not in PATH, but the shims are working correctly.
Possible causes and fixes:
  1. Terminal needs restart: Close and reopen your terminal/PowerShell
  2. PATH reload: Run: . scripts\reload-path.ps1
  3. Manual PATH: Add C:\Users\Admin\bin to your system PATH manually

If the diagnostic shows:

• ✓ Direct shim call works! → Your installation is fine, just reload PATH
• ✗ Shim files not found → Re-run bootstrap.py without arguments
• ✗ PATH not in registry → Run bootstrap with --debug to see what happened

Debug Mode

For detailed diagnostic output during installation:

python scripts\bootstrap.py --debug

This shows:

• Repo path detection
• Venv creation status
• Shim file creation details
• PATH registration results

Installation Steps (for "Other Computer")

1. Run bootstrap:

   python scripts\bootstrap.py
   

2. Check installation:

   python scripts\bootstrap.py --check-install
   

3. If 'mm' is not found:

   • Close and reopen your terminal (simplest), OR
   • Reload PATH: $env:PATH = [Environment]::GetEnvironmentVariable('PATH', 'User') + ';' + [Environment]::GetEnvironmentVariable('PATH', 'Machine')

4. Verify it works:

   mm --help
   

Shim File Locations

The installation creates Windows shim files in:

• User bin directory: C:\Users\<YourUsername>\bin\
• Files created:
  • mm.ps1 - PowerShell shim
  • mm.bat - Command Prompt shim

These files contain the absolute path to your project and venv, so they work from any location.

Why This Happens

On Windows, the PATH environment variable is read from the registry when a terminal session starts. If you change the registry PATH while a terminal is open, that terminal doesn't automatically pick up the change. That's why:

1. New terminals work: They read the updated registry PATH
2. Current terminal doesn't work: It still has the old PATH
3. Shim files still work: They can be called directly by absolute path

This is a Windows OS behavior, not a bug in the installation script.

Manual PATH Addition (If Registry Update Fails)

If for some reason the registry update fails (requires admin rights), you can add the path manually:

1. Open System Properties:

   • Press Win + X, select "System"
   • Click "Advanced system settings"

2. Click "Environment Variables"

3. Under "User variables," click "New"

   • Variable name: PATH
   • Variable value: C:\Users\Admin\bin

4. Click OK and close all terminals

5. Open a new terminal and test mm --help

Next Steps

Once mm works:

mm --help                    # Show all available commands
mm pipeline --help          # Get help for specific command
mm config --show           # Show current configuration

For more information, see the main README.