Installation Issues

GitHub CLI Authentication for Installer Download

Problem: gh release download shows a rate-limit warning or prompts for authentication.

Cause: The Nia release repository is public. gh release download works without authentication, but unauthenticated requests are subject to a lower GitHub API rate limit (60 requests/hour per IP). GitHub CLI may warn about this or prompt you to log in.

Solution:

Authenticate GitHub CLI to avoid rate-limit warnings:

gh auth login
gh auth status

Once authenticated, gh release download works without further prompts.

Prevention: Run gh auth login once on any machine where you use GitHub CLI.

Related: Installation Guide

Nia Binary Not Found in PATH

Problem: Shell cannot find the nia command after installation.

Error Message:

bash: nia: command not found

'nia' is not recognized as an internal or external command

Cause: The nia binary is either not installed or not in your system’s PATH environment variable.

Solution:

1. Verify the binary exists:

   # Linux/macOS
   which nia
   ls -l /usr/local/bin/nia
   
   # Windows (PowerShell)
   Get-Command nia
   

2. Check your PATH:

   # Linux/macOS
   echo $PATH
   
   # Windows (PowerShell)
   $env:PATH
   

3. Add nia to PATH (if installed but not in PATH):

   Linux/macOS:

   # If installed in custom location (e.g., ~/bin)
   export PATH="$PATH:$HOME/bin"
   
   # Make permanent - add to ~/.bashrc or ~/.zshrc
   echo 'export PATH="$PATH:$HOME/bin"' >> ~/.bashrc
   source ~/.bashrc
   

   Windows:

   # Add to user PATH
   $userPath = [Environment]::GetEnvironmentVariable("Path", "User")
   [Environment]::SetEnvironmentVariable("Path", "$userPath;C:\path\to\nia", "User")
   

4. Reinstall to standard location:

   # Linux/macOS
   sudo mv nia /usr/local/bin/nia
   
   # Windows - move to C:\Windows\System32 or add to PATH
   

5. Verify installation:

   nia --version
   

Prevention: Always install system-wide tools to standard locations like /usr/local/bin (Linux/macOS) or ensure custom installation directories are in your PATH.

Related: Installation Guide

Permission Denied Errors

Problem: Nia cannot execute due to insufficient permissions.

Error Message:

-bash: /usr/local/bin/nia: Permission denied

Error: Permission denied: .nia/work/

Cause: Either the binary lacks execute permissions, or nia cannot write to required directories (.nia/work/, .nia/config/).

Solution:

1. Fix binary permissions:

   # Linux/macOS
   chmod +x /usr/local/bin/nia
   ls -l /usr/local/bin/nia  # Should show -rwxr-xr-x
   

2. Fix work directory permissions:

   # Check current permissions
   ls -ld .nia/
   ls -ld .nia/work/
   
   # Fix permissions
   chmod 755 .nia/
   chmod 755 .nia/work/
   

3. Fix ownership (if wrong user owns the directory):

   # Check ownership
   ls -l .nia/
   
   # Fix ownership
   sudo chown -R $USER:$USER .nia/
   

4. Create missing directories:

   mkdir -p .nia/work/
   mkdir -p .nia/config/
   chmod 755 .nia/work/ .nia/config/
   

5. Check parent directory permissions:

   # Ensure you can write to current directory
   ls -ld .
   touch test.txt && rm test.txt  # Test write access
   

Prevention:

• Always use chmod +x after downloading binaries
• Avoid running nia with sudo (creates root-owned files)
• Initialize .nia/ directory in writable locations

Related: Installation Guide

Platform-Specific Issues

Linux Issues

Problem: Binary doesn’t run on older Linux distributions.

Error Message:

./nia: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.29' not found

Cause: Binary compiled with newer glibc than your system has.

Solution:

1. Check your glibc version:

   ldd --version
   

2. Update system (if possible):

   # Debian/Ubuntu
   sudo apt update && sudo apt upgrade
   
   # RHEL/CentOS
   sudo yum update
   

3. Use a supported host or container image with a compatible glibc version, or contact the Nia team for platform support.

Prevention: Check system requirements before downloading a release asset.

macOS Issues

Problem: macOS blocks unsigned binary from running.

Error Message:

"nia" cannot be opened because the developer cannot be verified

Cause: macOS Gatekeeper security prevents unsigned binaries from executing.

Solution:

1. Remove quarantine attribute:

   xattr -d com.apple.quarantine /usr/local/bin/nia
   

2. Or allow via System Preferences:

   • System Preferences → Security & Privacy → General
   • Click “Allow Anyway” next to the blocked message

3. Verify binary:

   nia --version
   

Prevention: Install the latest signed release and verify its checksum before running it.

Windows Issues

Problem: Windows Defender or antivirus blocks execution.

Error Message:

Windows protected your PC
This app might harm your PC

Cause: Unsigned executables trigger SmartScreen warnings.

Solution:

1. Allow via SmartScreen:

   • Click “More info”
   • Click “Run anyway”

2. Add exception to Windows Defender:

   # Run as Administrator
   Add-MpPreference -ExclusionPath "C:\path\to\nia.exe"
   

3. Verify and reinstall the latest release asset from telerik/project-nia.

Prevention: Use the latest signed release with a verified publisher certificate.

Windows Server-Specific Issues

This section covers issues specific to Windows Server editions (2019, 2022, 2025). For general Windows issues, see Windows Issues above.

Support Level: Windows Server 2025 is Tier 1 (Fully Supported), Server 2022 is Tier 2 (Supported), and Server 2019/2016 are Tier 3 (Community Supported). These solutions are based on testing and community feedback.

Command Not Found on Windows Server

Problem: nia command is not recognized even though the binary is installed and in PATH.

Error Messages:

'nia' is not recognized as the name of a cmdlet, function, script file, or operable program.

nia : The term 'nia' is not recognized as the name of a cmdlet...

Cause: Windows Server PowerShell sessions may not resolve extension-less commands the same way as Windows 11 client, especially in:

• Remote PowerShell sessions
• Scheduled tasks
• Services running as SYSTEM
• Constrained Language Mode environments

Solution:

1. Use explicit extension:

   # Instead of:
   nia --version
   
   # Use:
   nia.exe --version
   

2. Verify PATH includes installation directory:

   # Check current PATH
   $env:PATH -split ';' | Where-Object { $_ -like '*nia*' }
   
   # If empty, add Nia to the Machine PATH in an idempotent way:
   $installDir = "C:\Program Files\Nia"
   $machinePath = [Environment]::GetEnvironmentVariable("Path", "Machine")
   
   if ($machinePath -notlike "*$installDir*") {
       $newPath = $machinePath + ";" + $installDir
       [Environment]::SetEnvironmentVariable("Path", $newPath, "Machine")
   }
   

3. Use absolute path for scripts:

   # Most reliable method
   & "C:\Program Files\Nia\nia.exe" --version
   

4. Check PATHEXT includes .EXE:

   $env:PATHEXT
   # Should include: .EXE
   # If missing, contact your system administrator
   

Prevention:

• Always use nia.exe (with extension) in scripts and automation
• Document full path in runbooks and deployment scripts

Execution Blocked by Security Policy

Problem: Windows Server blocks execution due to security policy restrictions.

Error Messages:

This script is blocked. Only core types are supported in this language mode.

This app has been blocked by your system administrator.

Access is denied.

Cause: Windows Server environments often have stricter security policies:

• Execution Policy: Set to Restricted or AllSigned by default
• Constrained Language Mode: Enabled via Group Policy
• AppLocker: May block unsigned executables
• Windows Defender Application Control (WDAC): May require whitelist rules

Solution:

1. Check current Execution Policy:

   Get-ExecutionPolicy -List
   

2. For Execution Policy issues (if you have administrator rights):

   # View current policy
   Get-ExecutionPolicy
   
   # Set for current user (less privileged)
   Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
   
   # Or for machine (requires elevation)
   Set-ExecutionPolicy -Scope LocalMachine -ExecutionPolicy RemoteSigned
   

   Note: Execution Policy affects .ps1 scripts, not compiled .exe binaries. Nia binary should execute regardless of policy.

3. For AppLocker/WDAC restrictions:

   • Contact your IT administrator to whitelist the Nia binary
   • Provide SHA256 checksum for verification:

     Get-FileHash "C:\Program Files\Nia\nia.exe" -Algorithm SHA256
     

4. For Constrained Language Mode:

   # Check language mode
   $ExecutionContext.SessionState.LanguageMode
   
   # If "ConstrainedLanguage", executable binaries should still work
   # but PowerShell scripts may be restricted
   

5. Bypass for testing (not recommended for production):

   # Temporarily bypass for current process only
   powershell -ExecutionPolicy Bypass -Command "nia.exe --version"
   

Enterprise Resolution:

• Request IT to add Nia to approved software list
• Provide GPG signature and SHA256 checksum for security review
• Mirror a verified public release artifact in an approved internal package repository

SmartScreen Blocking on Windows Server

Problem: Windows SmartScreen blocks the binary as unrecognized.

Error Message:

Windows protected your PC
Microsoft Defender SmartScreen prevented an unrecognized app from starting.
Running this app might put your PC at risk.

Cause: Nia binaries are GPG-signed but not Authenticode-signed. SmartScreen blocks executables from unknown publishers.

Solution:

1. Unblock via PowerShell (recommended):

   # Check if file is blocked
   Get-Item "C:\Program Files\Nia\nia.exe" -Stream Zone.Identifier -ErrorAction SilentlyContinue
   
   # Unblock the file
   Unblock-File -Path "C:\Program Files\Nia\nia.exe"
   

2. Verify file integrity first (recommended before unblocking):

   # Download checksum file
   gh release download --repo telerik/project-nia --pattern '*.sha256'
   
   # Compare checksums
   $expected = (Get-Content nia-*-x86_64-windows.exe.sha256).Split(' ')[0]
   $actual = (Get-FileHash nia-*-x86_64-windows.exe -Algorithm SHA256).Hash
   if ($expected -eq $actual) { Write-Host "Checksum verified" }
   

3. Disable SmartScreen (not recommended, enterprise GPO may prevent):

   • Open Windows Security → App & browser control
   • Set “Check apps and files” to Off

4. Add Publisher Exception (via Group Policy for enterprise):

   • Computer Configuration → Administrative Templates → Windows Components → Windows Defender SmartScreen

Prevention:

• Verify checksums before running
• Use signed release assets from the public Nia repository
• Request enterprise IT to pre-approve via GPO

PATH Not Persisting Across Sessions

Problem: Nia is added to PATH but not recognized in new sessions.

Cause: PATH was added to process-level or user-level when system-level was needed, or terminal session wasn’t restarted.

Solution:

1. Check where PATH is defined:

   # Check all PATH sources
   Write-Host "Machine PATH:"
   [Environment]::GetEnvironmentVariable("Path", "Machine") -split ';' | Where-Object { $_ -like '*nia*' }
   
   Write-Host "User PATH:"
   [Environment]::GetEnvironmentVariable("Path", "User") -split ';' | Where-Object { $_ -like '*nia*' }
   
   Write-Host "Process PATH:"
   $env:PATH -split ';' | Where-Object { $_ -like '*nia*' }
   

2. Add to Machine PATH for all users:

   # Run as Administrator
   $machinePath = [Environment]::GetEnvironmentVariable("Path", "Machine")
   $niaPath = "C:\Program Files\Nia"
   if ($machinePath -notlike "*$niaPath*") {
       [Environment]::SetEnvironmentVariable("Path", "$machinePath;$niaPath", "Machine")
   }
   

3. Refresh current session:

   # Reload PATH in current session
   $env:PATH = [Environment]::GetEnvironmentVariable("Path", "Machine") + ";" + [Environment]::GetEnvironmentVariable("Path", "User")
   
   # Verify
   nia.exe --version
   

4. For services and scheduled tasks:

   • Services inherit PATH at startup time
   • Restart the service or use full path in service configuration

Prevention:

• Always add to Machine PATH on Windows Server
• Always restart PowerShell after PATH changes
• Use absolute paths in service configurations

Group Policy Blocking Execution

Problem: Enterprise Group Policy prevents running unsigned or untrusted executables.

Indicators:

• Binary runs fine in one session but not another
• Works for administrators but not standard users
• Works locally but not via remote PowerShell

Investigation:

1. Check applied policies:

   # View all applied GPOs
   gpresult /R
   
   # Export detailed report
   gpresult /H gpo-report.html
   

2. Check Software Restriction Policies:

   # View SRP
   Get-ChildItem "HKLM:\SOFTWARE\Policies\Microsoft\Windows\Safer" -Recurse
   

3. Check AppLocker rules:

   Get-AppLockerPolicy -Effective | Select-Object -ExpandProperty RuleCollections
   

Resolution (requires IT administrator):

1. For AppLocker: Add hash-based rule for nia.exe

   # Generate hash for IT team
   Get-AppLockerFileInformation -Path "C:\Program Files\Nia\nia.exe"
   

2. For WDAC: Request addition to CI policy

   • Provide signed policy fragment or hash

3. Alternative: Deploy a verified public release through your organization’s approved software distribution process.

PowerShell Constrained Language Mode

Problem: PowerShell is running in Constrained Language Mode, limiting script functionality.

Detection:

$ExecutionContext.SessionState.LanguageMode
# Output: "ConstrainedLanguage" indicates restricted mode

Impact on Nia:

• Direct binary execution (nia.exe) still works
• Complex PowerShell wrappers may fail
• Environment variable manipulation may be limited

Solution:

1. Direct execution still works:

   # This works even in CLM
   C:\Program Files\Nia\nia.exe --version
   

2. Avoid PowerShell features in automation:

   REM Use CMD batch files instead
   "C:\Program Files\Nia\nia.exe" --version
   

3. For full PowerShell functionality, request IT to:

   • Add your user to the language mode exemption group
   • Or use a different execution context

Enterprise Deployment Best Practices

For IT administrators deploying Nia across Windows Server environments:

Pre-Deployment Verification

1. Download and verify binary:

   # Download
   gh release download --repo telerik/project-nia --pattern 'nia-*-x86_64-windows.exe'
   gh release download --repo telerik/project-nia --pattern '*.sha256'
   gh release download --repo telerik/project-nia --pattern '*.asc'
   
   # Verify SHA256
   $expected = (Get-Content nia-*-x86_64-windows.exe.sha256).Split(' ')[0]
   $actual = (Get-FileHash nia-*-x86_64-windows.exe -Algorithm SHA256).Hash
   if ($expected -ne $actual) { throw "Checksum mismatch!" }
   
   # Verify GPG signature (requires GPG installed)
   gpg --import public-key.asc
   gpg --verify nia-*-x86_64-windows.exe.asc
   

2. Generate hash for AppLocker/WDAC:

   Get-FileHash nia-*-x86_64-windows.exe -Algorithm SHA256 | Format-List
   

Deployment Methods

Option A: Manual Deployment (Small Scale)

# Copy to servers via PowerShell remoting
$servers = @("server1", "server2", "server3")
$credential = Get-Credential

foreach ($server in $servers) {
    $session = New-PSSession -ComputerName $server -Credential $credential
    Copy-Item -Path ".\nia.exe" -Destination "C:\Program Files\Nia\nia.exe" -ToSession $session
    Invoke-Command -Session $session -ScriptBlock {
        Unblock-File "C:\Program Files\Nia\nia.exe"
        # Add to PATH
        $path = [Environment]::GetEnvironmentVariable("Path", "Machine")
        [Environment]::SetEnvironmentVariable("Path", "$path;C:\Program Files\Nia", "Machine")
    }
    Remove-PSSession $session
}

Option B: Group Policy Software Installation

1. Place nia.exe on network share
2. Create startup script:

   @echo off
   if not exist "C:\Program Files\Nia\nia.exe" (
       copy "\\fileserver\software\nia.exe" "C:\Program Files\Nia\nia.exe"
   )
   

3. Assign via Computer Configuration → Policies → Windows Settings → Scripts

Option C: SCCM/Intune Deployment

• Package as application with:
  • Install command: copy nia.exe "C:\Program Files\Nia\"
  • Detection rule: File exists at C:\Program Files\Nia\nia.exe
  • Dependencies: None

Post-Deployment Validation

# Test on each server type
Invoke-Command -ComputerName $servers -ScriptBlock {
    & "C:\Program Files\Nia\nia.exe" --version
} -Credential $credential

Updating Nia

For updates, replace the binary and verify:

foreach ($server in $servers) {
    # ... copy new version ...
    Invoke-Command -ComputerName $server -ScriptBlock {
        Unblock-File "C:\Program Files\Nia\nia.exe"
        & "C:\Program Files\Nia\nia.exe" --version
    }
}

Known Limitations on Windows Server

The following scenarios are known limitations:

1. No Authenticode Signing: Nia binaries use GPG signatures but not Authenticode (EV certificate). SmartScreen warnings will persist until the binary gains reputation or is code-signed.

2. Group Policy Override: Local workarounds may be overridden by domain Group Policy. Contact IT administrators for enterprise policy exceptions.

3. Server Core GUI Limitations: Shell completions and interactive features are limited on Windows Server Core. Use explicit commands.

4. Remote PowerShell Context: Some environment variables may not propagate correctly in PSRemoting sessions. Use absolute paths.