DocsTroubleshooting

Troubleshooting

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

macOS: env: node: no such file or directory

Unreal launched from Finder may not inherit your shell PATH.
Solutions:
  1. 1.Set Node path manually in Project Settings > Plugins > Blueprint Stack > Agents > NodePath.
  2. 2.Use the full path, for example /opt/homebrew/bin/node.
  3. 3.Or launch Unreal Engine from Terminal so PATH is inherited.

Agent shows "Not Installed"

Agent picker shows "Not Installed" status for a CLI agent.
Verify in terminal:
claude-code-acp --helpcodex-acp --help
Solutions:
  1. 1.Install the agent CLI with its documented install command.
  2. 2.Restart Unreal so PATH changes are picked up.
  3. 3.Or set the explicit executable path in agent settings (ClaudeCodePath / CodexPath).

Agent shows "Missing API Key"

Agent requires an API key or auth session to function.
Solutions:
  1. 1.Run auth for the agent (e.g. claude auth login or codex login).
  2. 2.Or set the required environment variable (ANTHROPIC_API_KEY, OPENAI_API_KEY).

MCP server port conflict

Another application is already using port 9315.
Solutions:
  1. 1.Change the port in Project Settings > Plugins > Blueprint Stack > MCP Server > McpPort.
  2. 2.The plugin auto-probes nearby ports if the configured port is occupied.

Prompt stuck / no response

The AI appears to be processing but never responds.
Solutions:
  1. 1.Use the cancel button and resend the prompt.
  2. 2.Open a fresh session.
  3. 3.Check the Output Log for LogTemp entries prefixed with BlueprintStack:.

401 OAuth token expired (Codex)

OAuth token has expired.
Solutions:
  1. 1.Run codex login in a terminal outside Unreal and complete auth.
  2. 2.Restart Unreal Editor.

Tool execution timeout

Default timeout is 60 seconds; long-running tools may exceed it.
Solutions:
  1. 1.Increase ToolTimeoutSeconds in Project Settings > Plugins > Blueprint Stack.

Image / 3D generation not working

Generation features require separate API keys.
Solutions:
  1. 1.Set ImageApiKey (OpenAI) in Project Settings > Plugins > Blueprint Stack > Generation.
  2. 2.Set MeshyApiKey in the same section for 3D mesh generation.