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, out of date, or unavailable because the provider is disconnected. Resolve that state using the project’s normal source-control tools, then refresh or retry in Locus.

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.

Checkout or Mark for Add failed

Confirm Unreal’s source-control provider is connected and can report the file. A newly created local file remains on disk if Mark for Add fails. Retry after restoring the provider; do not recreate the item unless you have verified the existing file.

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, 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.

Asset reference is missing or stale

Try locating the asset in the Content Browser and refresh discovery. A moved or deleted asset can leave a readable but unresolved reference. Locus keeps unresolved references visible so you can repair or remove them deliberately.

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.

Documents are missing

Confirm the .md file is beneath <Project>/ProjectDocuments/, uses valid UTF-8, and maps to the expected physical or Content Browser context. Refresh Documents. Remember that Documents are external virtual 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.

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. The current plugin revision has Give Feedback but does not yet register an Editor Documentation command.