Troubleshooting

Start with the symptom below. Preserve project files before making any manual storage change.

Locus is missing or does not load

1. Confirm the plugin is at <Project>/Plugins/Locus/ and enabled in Edit > Plugins.
2. Confirm the package matches the project’s exact Unreal Engine minor version.
3. Restart Unreal Editor after enabling or replacing the plugin.
4. Try Window > Locus or Ctrl+Shift+L.
5. Review the Unreal Output Log for the LogLocus category and the plugin load error.

If a binary package targets another Engine minor version, replace it with the correct package; do not copy individual binaries between packages.

Content is read-only

Open Source Control and check whether the file is controlled, checked out by another user or client, out of date, or unavailable because the configured provider is disconnected. A clean controlled Note or Document also remains read-only until you explicitly check it out; a controlled Shared Pin requests checkout when you attempt a supported mutation.

Check Out may be unavailable when another client owns the file, your workspace is behind the depot, or the provider cannot report a safe state. Resolve ownership or revision state using the project’s normal source-control workflow. After reconnecting a provider, refresh Unreal Source Control or Locus; controlled content remains read-only until checkout succeeds. Do not bypass protection by changing filesystem permissions.

Private Notes and Pins should not depend on a provider. If they are unavailable, verify that the project Saved/Locus storage exists and is writable.

If Unreal has no source-control provider configured, Locus intentionally shows no source-control-specific status, tooltip, guidance, Check Out, or Mark for Add UI. That is normal Local Mode, not a missing status. A provider that is configured but unavailable is different and keeps known controlled content protected.

Checkout or Mark for Add failed

Confirm Unreal’s source-control provider is configured, connected, and able to report the file. For controlled content, check ownership and whether your workspace is at the current depot revision before retrying Check Out. A newly created Shared Note remains on disk if its post-create Mark for Add request fails; retry after restoring the provider, and do not recreate it unless you have verified the existing file. New Shared Pins and Documents are intentionally Untracked until you explicitly choose Mark for Add, so organize them first and add them only when ready. Shared Pin Snapshot images have separate source-control state.

A Document will not rename or move

Use the Locus Documents workspace for rename and move; the Content Browser item is a projection, not the authoritative rename surface. An eligible Untracked Document can be renamed with Rename or F2, and moved with Move or drag and drop onto a valid existing folder. Locus intentionally blocks Rename and Move for Marked-for-Add and controlled Documents because it cannot safely perform a provider-neutral source-control move. Do not work around this by disabling source control or changing filesystem permissions; organize the Document before Mark for Add instead.

Notes, Pins, or Documents do not refresh

Use the active workspace’s rebuild or refresh action. For Documents changed in an external editor, save a valid UTF-8 .md file beneath ProjectDocuments. For Pins, confirm that the current world is saved and that the Pin is associated with its resolved map.

Recovery is available

Review the authoritative disk item and the recovery snapshot before acting. Restore replaces the authoritative item with recovered work, Restore as New preserves both, and Discard removes the snapshot. Prefer restoring as new when you are unsure.

Do not clean Saved as a troubleshooting shortcut

The project Saved tree can contain Private Notes, Private Pins, Private Pin Snapshots, and recovery snapshots. Deleting it can permanently destroy user content.

External conflict

An external conflict means the disk file changed while Locus held unsaved edits. Do not force an overwrite. Use the offered actions to reload disk, save local work as a new item, copy local text, or compare versions where available.

Malformed or unsupported data

Keep the original file and inspect the LogLocus message. Do not hand-edit identifiers or ownership fields unless you have a verified backup and understand the format. An invalid UTF-8 Markdown file is rejected for import. Unsupported Markdown should remain intact as source even if Read Mode cannot present it fully.

A reference is missing or stale

Refresh the relevant workspace and verify the referenced Asset, Pin, Note, Document, or Actor still exists. A moved or deleted target can leave a readable but unresolved reference. Locus keeps unresolved references visible so you can repair or remove them deliberately.

Actor references can be authored only by dragging exactly one eligible loaded Actor from the World Outliner into an editable Note or Document. They do not appear in Insert Reference or the @ picker. Actors inside Level Instances and unsupported transient or preview worlds cannot be referenced.

Pins are unavailable

Persistent Pins require a saved top-level Editor world. Save the map, return to Current Map, and retry placement. Pin files do not load or modify maps merely for All Maps browsing. Snapshot capture and update additionally require an available perspective Level Editor viewport and are unavailable during PIE.

Documents are missing

Confirm the .md file is beneath <Project>/ProjectDocuments/ and uses valid UTF-8. A path outside the reserved Content/ subtree appears beneath Locus Documents and does not project into Unreal’s Content Browser. A path beneath ProjectDocuments/Content/ appears beneath the sparse Content Browser root and projects into the matching /Game context. Refresh Documents after external changes. Unrelated /Game folders are intentionally absent because the tree is derived from indexed Documents, not Asset Registry folders. Remember that Documents are external projected items, not UAssets.

Markdown does not render as expected

Check Documents for supported constructs. Raw HTML and unsafe URLs remain inert, remote content is not fetched, and browser-equivalent Markdown rendering is not promised. Switch to Edit Mode to confirm the authoritative source is intact.

MCP client does not connect or is denied

Keep Unreal Editor open and use Editor Preferences > Plugins > Locus > MCP Integration to confirm that Enable MCP is on and the status is running. If the local endpoint or client configuration is unavailable, copy a fresh configuration after changing the local port or regenerating the credential.

Choose the matching Client Format before copying. Run Claude Code and Gemini CLI registration commands in a normal terminal rather than inside their interactive prompts. Gemini uses user scope, so an older global locus entry may still point to another project’s endpoint; replace it using a fresh configuration from the currently open project. Never paste the copied command or credential into a support request.

Only one client can own the active Locus session. Close or disconnect the previous client, wait briefly, and retry; use Reset Active Client only when that client is no longer in use. A mutation requires Allow Changes, and Private Notes or Pins require Allow Private Notes and Pins separately. MCP Pin work is limited to the supported saved project-owned /Game/... world baseline.

See MCP Integration for the complete connection, permission, supported-tool, and Pin-context guidance.

Documentation or feedback does not open

External links use the operating system’s default browser. Check that a default HTTP/HTTPS browser is configured and that the operating system permits URL launch. Failure does not change project data. MCP Integration includes a Documentation button, and Locus also provides Give Feedback.