Installation Issues

Common issues and solutions for KubeGraf installation and usage across different platforms.

Installation Issues

Windows Issues

"kubegraf is not recognized" - PATH Configuration

If you see this error after manual installation:

kubegraf : The term 'kubegraf' is not recognized as the name of a cmdlet, function, script file, or operable program.

The issue: The directory containing kubegraf.exe is not in your system PATH environment variable.

Step-by-Step: Add Folder to PATH Permanently

Method 1: Using PowerShell (Recommended)

  1. Open PowerShell as Administrator (right-click PowerShell → Run as Administrator)
  2. Find where you extracted kubegraf.exe (e.g., C:\kubegraf)
  3. Run this command, replacing C:\kubegraf with your actual path: 
    [Environment]::SetEnvironmentVariable("Path", $env:Path + ";C:\kubegraf", [EnvironmentVariableTarget]::User)
  4. CRITICAL: Close ALL open terminal windows (PowerShell, CMD, Git Bash, etc.)
  5. Open a NEW terminal window
  6. Test: kubegraf --version

Method 2: Using Windows System Settings (GUI)

  1. Press Win + X → Select "System"
  2. Click "Advanced system settings" on the right
  3. Click "Environment Variables" button at the bottom
  4. In "User variables" section, select "Path" → Click "Edit"
  5. Click "New" → Paste your folder path (e.g., C:\kubegraf)
  6. Click OK on all dialogs to save
  7. CRITICAL: Close ALL terminal windows and open NEW ones
  8. Test: kubegraf --version

⚠️ Important: PATH changes only affect NEW terminal sessions. Already-open terminals will NOT see the updated PATH. You must close and reopen your terminals for the changes to take effect.

Quick Test (Temporary)

# Only works in current PowerShell session
$env:Path += ";C:\kubegraf"
kubegraf --version

Use this to test if kubegraf.exe works before adding to PATH permanently.

Verify PATH was Added

# Check if folder is in PATH
$env:Path -split ';' | Select-String 'kubegraf'

Should show your kubegraf folder path if correctly added.

"Running scripts is disabled"

If you get this error when running PowerShell scripts:

.\install.ps1 : File C:\Users\...\install.ps1 cannot be loaded because running scripts is disabled on this system.

✅ Solution 1: Bypass (Recommended)

Invoke-WebRequest -Uri https://kubegraf.io/install.ps1 -OutFile install.ps1
powershell -ExecutionPolicy Bypass -File install.ps1

No permanent changes to your system.

Solution 2: Change execution policy

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser -Force

Then run installation normally. This change persists.

macOS & Linux Issues

macOS: Homebrew permission errors

If you see "directories are not writable" error:

Error: The following directories are not writable by your user:
/usr/local/share/man/man8

Solution: Fix permissions with:

sudo chown -R $(whoami) /usr/local/share/man/man8
chmod u+w /usr/local/share/man/man8

brew tap kubegraf/tap
brew install kubegraf

macOS: "kubegraf cannot be opened"

If you see a security warning on macOS:

sudo xattr -rd com.apple.quarantine /usr/local/bin/kubegraf

This removes the quarantine attribute that prevents unsigned binaries from running.

Linux: Permission denied

If you get permission errors when running kubegraf:

sudo chmod +x /usr/local/bin/kubegraf

This makes the binary executable for all users.

Previous
Installation
Next
CrashLoopBackOff