Start with the companion’s Run diagnostics, then inspect the failing stage. Configuration, MCP transport, source validation, native builds and gameplay are separate checks; a useful report names which one failed and includes its evidence.
The companion or server will not start
For an installer setup, open Apothicon from the Start menu. For a source setup, extract the complete project folder and run Start-Apothicon.cmd from that copy. The first installation needs internet for the private environment and dependencies. For a manual installation, use Python 3.11 or newer with Tk support.
If you moved the project, reconnect your client so its executable and apothicon.toml paths point to the new location. Open the configuration from the companion and check for malformed TOML, invalid paths or an unintended environment override.
Developer diagnostics can export a JSON report. It includes local paths and configuration status, so review it before sharing publicly. Logging uses stderr; MCP stdout is reserved for protocol messages.
The client cannot see Apothicon
Save settings, connect the selected client and start a new agent session. Test MCP connection verifies initialization and a real read-only tool call; the AI client’s own status confirms whether that session loaded the registration.
An unavailable connection means client detection did not find an executable or supported extension. Use the information icon, then Refresh detection. A leftover configuration file alone does not count as an installation.
For profile-dependent clients, use Copy setup in their active MCP settings. If a foreign registration already uses apothicon, rename that registration before connecting. See manual connection setup.
Saved settings seem to be ignored
Check APOTHICON_CONFIG, APOTHICON_WORKSPACE, BO3_MOD_TOOLS and APOTHICON_ALLOW_BUILDS. Environment values override the file. Relative workspace and log paths resolve against the configuration file, not whichever directory happens to launch the client.
Restart the agent session after changes. The existing MCP process retains its loaded configuration.
A map edit is rejected
Read the exact conflict or unsupported-source result. Save and reload Radiant around external edits. Hash conflicts mean the source changed; inspect the fresh source and regenerate the preview instead of forcing an old edit through.
Unknown geometry grammar, ambiguous startup scopes and incomplete stock exemplars fail deliberately before mutation. Use inspect_map, inspect_prefab_hierarchy or script inspection to narrow the issue. edit_history, undo_edit and recover_workspace provide journalled recovery paths.
A native build cannot run
Check installation_doctor, the configured Mod Tools folder and the local execution setting. The tool call also needs execute=true. A fresh installation may have tools present but still need the GDT stage before compiling.
Deploy staged source before building. Keep full compilation after geometry, lighting or prefab changes. Inspect build_status and diagnose_build_log; do not infer success from an old BSP, LED or fastfile. Fresh artifact checks and exact-source lighting evidence are part of completion.
Search returns a fallback
Keyword search works without an embedding model. An auto fallback is expected when semantic indexing is unprepared. Use Prepare semantic docs only when you want that optional setup. knowledge_status and index_installation identify absent or stale local reference coverage.
What counts as validated?
| Result | What it establishes |
|---|---|
| Source checks pass | The inspected structural and static contracts passed. |
| Compile, light and link succeed | The installed native stages accepted those inputs and produced checked outputs. |
| A game process starts | The owned process launched. |
| An observed playtest check passes | The specific behavior was observed under the recorded conditions. |
Previous acceptance runs have limited scope. Current generated maps and new feature combinations need their own native visual and ordinary-play acceptance. Keep rendering, collision, navigation, progression, purchases, co-op, late join and restart pending until the relevant checks are actually observed.