Skip to content
Hosihikari Framework

Troubleshooting

The log reports api_version 不匹配 or manifest_version 不匹配

Section titled “The log reports api_version 不匹配 or manifest_version 不匹配”

The plugin was built against another contract. The current contract is api_version 2 and manifest manifest_version 1; rebuild with Hosihikari.Plugin.Abstractions 1.1.0. Editing the number in the manifest does not change the type surface.

The log reports 没有能处理 loader=... 的加载器

Section titled “The log reports 没有能处理 loader=... 的加载器”

The matching loader is not installed or not enabled, or the plugin does not depend on it. Source plugins install CSharpLoader / FSharpLoader and list hosihikari-csharp / hosihikari-fsharp in dependencies; out-of-process plugins install RpcLoader and list hosihikari-rpc.

The log reports 清单 name 必须等于目录名

Section titled “The log reports 清单 name 必须等于目录名”

The directory name and name must match exactly; rename one of them.

The log reports entry 必须是包内相对路径

Section titled “The log reports entry 必须是包内相对路径”

entry must point inside the package; remove absolute paths and ...

The plugin loads but receives no events or timers before enable

Section titled “The plugin loads but receives no events or timers before enable”

The framework opens the scope gate after a successful OnEnable. Periodic work registered in OnLoad starts receiving callbacks only after enable; start periodic work in OnEnable.

Configuration does not take effect

Section titled “Configuration does not take effect”
  • The package default is <name>.conf, matching the plugin name.
  • The server override is config/hosihikari/<name>.conf.
  • Environment variables override the same keys; key matching is case-insensitive.
  • Layering goes through the framework's provider chain; HOCON include does not apply.

Where does data go?

Section titled “Where does data go?”

data/hosihikari/<name>/. ctx.DataDirectory (Node/Python) or context.DataDirectory (.NET) points there.

An out-of-process plugin does not start

Section titled “An out-of-process plugin does not start”
  • The executable is not on PATH: the log shows a spawn failure or the process exits immediately.
  • Endstone: the CLI replaces the child PATH; use an absolute path in command.
  • The plugin writes non-protocol output to stdout: stdout carries JSON-RPC; logs go to stderr or logInfo.

Nothing is reclaimed after unload

Section titled “Nothing is reclaimed after unload”
  • Static fields, singletons, and raw threads keep the ALC alive; stop threads, unsubscribe, and clear references in OnUnload.
  • Native libraries live for the process; unload reclaims the managed ALC only.
  • The framework reclaims its own event subscriptions and timers; plugin-owned resources are the plugin's job.