Skip to content

Troubleshooting

Jump to bottom
Recep Samet Yıldız edited this page Sep 1, 2026 · 1 revision

Troubleshooting

Common errors, log categories, and a systematic debug checklist for UEBPCracker.

Log Categories

Category What it covers
LogUEBPCracker All plugin operations, tool calls, security decisions
LogModelContextProtocol Unreal MCP server events, connections, tool dispatch
LogBlueprintUserMessages K2 compiler messages from Blueprint compile

Increase verbosity

In the Editor console (Output Log):

Log LogUEBPCracker Verbose
Log LogModelContextProtocol Verbose

Startup Checklist

Before debugging any tool call failure, verify:

  • Plugin is loaded: Edit → Plugins → UEBPCracker shows as enabled
  • MCP server started: LogModelContextProtocol: Server started on port 8000 in Output Log
  • AI client is connecting to http://127.0.0.1:8000/mcp
  • health_check returns success: true
  • bWriteEnabled: true in health_check response (if write operations needed)
  • Toolset is visible: describe_toolset UEBPCrackerEditor.UEBPCrackerToolset returns tool list
  • After any new UFUNCTION added: full editor restart (Live Coding does not update MCP tool list)

Common Errors and Solutions

UEBP.PATH_OUTSIDE_ALLOWED_ROOT

Symptom: Write operation rejected before any mutation.

Causes:

  • Target path (e.g. /Game/Blueprints/BP_Test) is not inside the configured write root (default /Game/AI/)
  • Segment-boundary check: /Game/AI does NOT match /Game/AIEvil

Fix: Either change the target path to be inside /Game/AI/, or add the desired root to AllowedWriteRoots in DefaultUEBPCracker.ini.

UEBP.OPERATION_NOT_ALLOWED / Write gate error

Symptom: Any write tool returns this error.

Cause: bEnableWriteOperations=False (the default).

Fix:

[/Script/UEBPCrackerEditor.UEBPCrackerSettings]
bEnableWriteOperations=True

Restart the editor after changing INI (Live Coding does not reload UDeveloperSettings).

UEBP.EVENT_ALREADY_IMPLEMENTED

Symptom: add_node event_override ReceiveBeginPlay fails on a newly created Blueprint.

Cause: New Actor Blueprints ship with default ReceiveBeginPlay, ActorBeginOverlap, and Tick event nodes.

Fix: Use inspect_blueprint to find the existing event node's GUID, then reference it directly instead of creating a new one. Or apply a spec (which removes default nodes automatically before adding spec nodes).

UEBP.SPEC_TARGET_ALREADY_EXISTS

Symptom: apply_blueprint_spec fails immediately.

Cause: The Blueprint at target.path already exists. Spec executor is create-only.

Fix: Either delete the existing Blueprint, use a different target path, or use plan_blueprint_patch / apply_blueprint_patch to update the existing Blueprint.

UEBP.PLAN_HASH_REQUIRED / UEBP.PLAN_HASH_MISMATCH

Symptom: apply_blueprint_patch returns one of these errors.

Causes:

  • PLAN_HASH_REQUIRED: You didn't pass expected_plan_hash to ApplyBlueprintPatch
  • PLAN_HASH_MISMATCH: The Blueprint changed between planning and apply, OR the security policy changed

Fix: Re-run PlanBlueprintPatch to get a fresh plan hash, then immediately apply it.

UEBP.OPERATION_BUSY

Symptom: Write tool returns this error.

Cause: Another write operation is currently in progress (serial mutation — concurrent writes are rejected).

Fix: Wait for the in-progress operation to complete. The error is bRetryable: true — retry after a short delay. If the operation seems stuck, check the editor Output Log for errors in LogUEBPCracker.

UEBP.DIRTY_ASSET_PROTECTED

Symptom: Mutation attempt blocked.

Cause: The target Blueprint has unsaved changes from another source (manual editor edits, previous failed operation, etc.).

Fix: Save the Blueprint in the editor first (Ctrl+S in Content Browser), then retry the tool call.

Compile fails after add_node

Symptom: add_node succeeds, but commit pipeline fails at compile stage.

Common causes:

  1. Wrong event name — BeginPlay instead of ReceiveBeginPlay
  2. Connected pin type mismatch — check with resolve_unreal_type first
  3. Unresolved function path — verify the exact function path with inspect_blueprint on a BP that already has that node

Fix: Check compileErrors[] in the response for the first error. The first error line is the real problem (not the cascading errors below it).

MCP server doesn't start

Symptom: http://127.0.0.1:8000/mcp is unreachable.

Checklist:

  1. Check Output Log for LogModelContextProtocol messages
  2. Try starting manually: editor console → ModelContextProtocol.StartServer 8000
  3. Check if another process is using port 8000 (netstat -an | findstr 8000)
  4. Verify ModelContextProtocol plugin is enabled in Edit → Plugins
  5. If using -ExecCmds="ModelContextProtocol.StartServer 8000" on command line: this fires reliably ~3/4 times. If it fails, use the console command inside the editor instead.

-ExecCmds doesn't fire

Symptom: Command is logged (Cmd: ModelContextProtocol.StartServer 8000) but no handler output.

Cause: Known UE 5.8 reliability issue — occurs ~1 in 4 boots. See UE 5.8 Gotchas.

Fix: Start the server manually from the editor console after boot.

"Missing Modules" dialog on editor start

Symptom: Editor shows a dialog saying modules are missing.

Cause: Build is out of date, or plugin was moved without regenerating project files.

Fix:

  1. Close the dialog (don't click "Open in Visual Studio" yet)
  2. Regenerate project files (right-click .uproject)
  3. Rebuild in Visual Studio: Development Editor / Win64
  4. Check the UBT output for the first real C++ error

Editor spawns a second instance / UEBPCrackerHost_2.log

Symptom: Test scripts aren't hitting the expected editor instance.

Cause: The editor launched a second instance (possibly due to a file watcher or a previous crash).

Fix: Kill all UnrealEditor.exe processes and restart cleanly. When running tests, check all log files in Saved/Logs/ — the secondary instance writes to UEBPCrackerHost_2.log.

"Restore Packages" dialog on boot

Symptom: Editor shows a package restore prompt on startup, blocking automation.

Cause: Previous editor instance was force-killed with dirty packages.

Fix:

  1. Answer the dialog (TAB+ENTER — Slate dialogs have no UIA automation buttons)
  2. Or clear Saved/Autosaves/ before starting the editor

Headless test exits with code 255

Symptom: UnrealEditor-Cmd.exe ... -ExecCmds="Automation RunTests UEBPCracker;Quit" exits with 255.

Meaning: Test failures (GIsCriticalError set by the automation framework). Exit code 0 = all pass.

Fix: Check the test report at the -ReportExportPath directory — index.json lists individual test results. For verbose output, also check Saved/Logs/UEBPCrackerHost.log (note: -log=custom.log is ignored by UnrealEditor-Cmd).

Diagnostic Commands

# Check what's listening on port 8000
netstat -an | findstr "8000"

# Find all UEBPCracker log entries
Select-String -Path "Saved\Logs\UEBPCrackerHost.log" -Pattern "LogUEBPCracker"

# Quick MCP connectivity test (PowerShell)
$body = '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
Invoke-RestMethod -Uri "http://127.0.0.1:8000/mcp" -Method POST -Body $body -ContentType "application/json"

Getting Help

  • Check UE 5.8 Gotchas for engine-specific quirks
  • Open a GitHub Issue with the bug report template
  • Include: UE version, plugin version, full tool call JSON, structured response JSON, relevant LogUEBPCracker log output

See Also

Clone this wiki locally