DocsTroubleshooting

Troubleshooting

Quick fixes for the most common installation, authentication, and runtime issues.

401 OAuth token expired (Codex)

OAuth token has expired
Solutions:
  1. 1.Open your terminal outside Unreal.
  2. 2.Run codex login and complete auth.
  3. 3.Restart Unreal Editor and reconnect the Codex runtime.

macOS: env: node: no such file or directory

Unreal launched from Finder may not inherit your shell PATH.
Solutions:
  1. 1.In Unreal, set Node path manually in Project Settings > Plugins > Blueprint AI > BAI Agents > Path Overrides > Node.js.
  2. 2.Use the full Node path (for example /opt/homebrew/bin/node).
  3. 3.Optional: launch Unreal from Terminal so PATH is inherited.

Runtime shows Not installed

Agent picker shows "Not installed" for CLI agents.
Verify in terminal:
claude --versiongemini --versioncodex --version
Solutions:
  1. 1.Install the runtime CLI with its documented install command.
  2. 2.Restart Unreal so process PATH changes are picked up.
  3. 3.Or set explicit executable path in Path Overrides.

Runtime says Needs API key

Agent requires an API key to function.
Solutions:
  1. 1.Add the required key in project settings (for example OpenRouter API key for the built-in OpenRouter runtime), then reopen the tab or start a new session.

Prompt is stuck / no final output

The AI appears to be processing but never responds.
Solutions:
  1. 1.Use the cancel button and send the prompt again.
  2. 2.Open a fresh tab/session with the same runtime.
  3. 3.Check Unreal Output Log for LogBlueprintAI errors.

MCP server port conflict

Another app already uses the preferred MCP port.
Solutions:
  1. 1.Change: Project Settings > Plugins > Blueprint AI > MCP Server > Preferred MCP Port