Troubleshooting

Start with the earliest failed layer.

Startup

  1. Confirm the log reports FTK2.ModAPI 0.5.9 and the supported runtime versions.
  2. Keep exactly one FTK2.ModAPI.dll under BepInEx\plugins.
  3. Confirm the consumer declares a BepInEx dependency on org.ftk2.modapi.
  4. Find its MOD_REGISTERED entry before debugging content.

Registration and ownership

  • INVALID_CONTENT_OWNER means a content/localization namespace does not match the registered mod ID.
  • Duplicate IDs are preserved rather than overwritten.
  • Subscribe in Awake; GameDataReady events are not replayed.
  • MAIN_THREAD_REQUIRED means a runtime service was called from a worker thread. Move that call to the Unity main thread.

Custom items

Check template creation, localization, definition registration, ability/passive dependencies, and activation in that order. CannotDeactivateWhileReferenced means a tracked runtime item or dependent definition must be released first.

Custom abilities

Check ability localization/template/registration/activation before the dependent item. Then verify the item carries the custom ID and an appropriate ItemSkillRoll. Existing status IDs must exist in the current FTK2 data.

FTK2 1.14.6 uses worker threads during combat asset preload. ModAPI 0.5.9 handles its own presentation/icon diagnostics safely there. A remaining MAIN_THREAD_REQUIRED report should include the complete stack trace so the caller can be identified.

Save load is blocked

Restore the mod that owns each reported missing custom ID. Do not bypass the preflight and force an unsafe commit. See Save Compatibility.

Use Reporting a Useful Bug for the report bundle.