IntelligenceX

PowerShell Troubleshooting

Edit on GitHub

Fix common IntelligenceX PowerShell issues around transport startup, auth, module loading, and runtime configuration.

PowerShell Troubleshooting

Common issues and direct fixes for IntelligenceX PowerShell usage.

Connect-IntelligenceX Fails With Executable Not Found

Symptom:

  • Connect-IntelligenceX -Transport AppServer throws an error about Codex app-server not found.

Fix:

Connect-IntelligenceX -Transport AppServer -ExecutablePath "C:\tools\codex.exe"

Fallback:

Connect-IntelligenceX -Transport Native

Login Never Completes

Symptom:

  • Wait-IntelligenceXLogin times out.

Fix checklist:

  1. Start login again and open the exact URL from AuthUrl.
  2. Wait using explicit login id.
  3. Verify account after completion.
$login = Start-IntelligenceXChatGptLogin
Write-Output $login.AuthUrl
Wait-IntelligenceXLogin -LoginId $login.LoginId -TimeoutSeconds 300
Get-IntelligenceXAccount

Raw Output Needed But Typed Result Missing Field

Use -Raw to inspect full payload:

Get-IntelligenceXMcpServerStatus -Raw
Get-IntelligenceXConfig -Raw
Invoke-IntelligenceXRpc -Method "config/read"

MCP OAuth Never Starts

Symptom:

  • No server is found for OAuth workflow.

Fix:

  • Filter using enum-safe auth status.
  • Reload MCP config if files changed.
Invoke-IntelligenceXMcpServerConfigReload

$status = Get-IntelligenceXMcpServerStatus
$oauthStatus = [IntelligenceX.OpenAI.AppServer.Models.McpAuthStatus]::OAuth
$oauthServer = $status.Servers | Where-Object { $_.AuthStatus -eq $oauthStatus } | Select-Object -First 1

if ($oauthServer) {
    Start-IntelligenceXMcpOAuthLogin -ServerName $oauthServer.Name
}

Turn Is Stuck Or Running Too Long

Stop-IntelligenceXTurn -ThreadId $thread.Id -TurnId $turn.Id

Then continue from the same thread:

Resume-IntelligenceXThread -ThreadId $thread.Id

Need To Rewind Conversation State

Restore-IntelligenceXThread -ThreadId $thread.Id -Turns 1

Health Checks For Diagnostics

Get-IntelligenceXHealth
Get-IntelligenceXHealth -Copilot

Enable detailed transport diagnostics:

Connect-IntelligenceX -Diagnostics
Watch-IntelligenceXEvent

Script Hygiene

Always disconnect in finally:

try {
    $client = Connect-IntelligenceX
    Initialize-IntelligenceX -Client $client -Name "Troubleshoot" -Title "Troubleshoot" -Version "1.0.0"
    Get-IntelligenceXHealth -Client $client
} finally {
    if ($client) {
        Disconnect-IntelligenceX -Client $client
    }
}