DocsTroubleshooting

Troubleshooting

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

Local agent: "Couldn't reach Ollama / LM Studio"

The local model server is not running, or the configured host is wrong.

Solutions:

  1. 1.Ollama: open the Ollama app or run ollama serve, then resend the prompt. Make sure a model is pulled (ollama pull llama3.1).
  2. 2.LM Studio: open the Developer tab, load a model, click Start Server, then resend the prompt.
  3. 3.Confirm the server is reachable in a browser: http://127.0.0.1:11434/api/tags (Ollama) or http://127.0.0.1:1234/v1/models (LM Studio).
  4. 4.If you changed the port, update the Host field in Blueprint Stack panel > Settings > Local LLM (Ollama) or > LM Studio.

Local model: empty model dropdown or weak tool use

No model is loaded, or the chosen model handles tool calls poorly.

Solutions:

  1. 1.Ollama: pull at least one model and confirm it shows in ollama list. The dropdown is built from your Ollama library.
  2. 2.LM Studio: load a model into the server (not just download it) — the server reports an empty list otherwise.
  3. 3.Pick a tool-calling-capable model (Llama 3.1, Qwen2.5, or similar). Very small models (1B–3B) often loop or ignore tools — try a 7B+ instruction-tuned model, or raise the model's context length.

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.
  4. 4.This only affects CLI-based agents (Claude Code, Codex). The local agents (Ollama, LM Studio) need no Node.js.

Agent shows "Not Installed"

Agent picker shows "Not Installed" status for a CLI agent.

Verify in terminal:

claude-code-acp --help
codex-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.