IntelligenceX

PowerShell Troubleshooting

Edit on GitHub

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
    }
}