Troubleshooting & Support

Before You Troubleshoot

Record Minecraft, Paper, Java, ModelEngine, PacketEvents, and FancyHolograms versions. Save the startup log and the exact command or action that failed. Never share passwords, tokens, or unrelated private data.

Installation and Startup

Symptoms: ModelEngineNPC does not appear in /plugins, or startup reports dependency errors.

Likely causes: Java or Paper version is unsupported; ModelEngine or PacketEvents is missing; the JAR is in the wrong directory.

Diagnostic steps: Check the startup log, /plugins, Java version, and dependency load state.

Fix: Install required dependencies, place the JAR in plugins/, stop the server fully, and start it again. Do not use /reload.

Verification: Console shows [ModelEngineNPC] ModelEngineNPC enabled! and /plugins lists the plugin.

Escalation: Include startup log excerpt and exact versions in a support report.

Dependencies

Symptoms: NPC creation or feature commands fail with missing-plugin errors.

Likely causes: ModelEngine and PacketEvents are required. FancyHolograms is required only for hologram features.

Diagnostic steps: Confirm required plugins are enabled before ModelEngineNPC and inspect dependency errors.

Fix: Install compatible ModelEngine and PacketEvents versions. Install FancyHolograms when using holograms.

Verification: Restart cleanly and repeat the smallest failing command.

Escalation: Report dependency versions and the first relevant console error.

NPC Rendering

Symptoms: Model NPC does not render, or normal NPC appears incorrectly.

Likely causes: ModelEngine model ID is missing or model data has not loaded; normal NPC packet integration is unavailable.

Diagnostic steps: Run /menpc list, confirm ModelEngine model ID, and inspect console output.

Fix: Load the model in ModelEngine, use the exact model ID, and verify PacketEvents is enabled for normal NPCs.

Verification: Recreate or respawn NPC and confirm it appears at the expected location.

Escalation: Include NPC type, command, model ID, and console error.

Skins

Symptoms: Normal NPC appears as Steve or skin arrives late.

Likely causes: Skin fetching is asynchronous and the remote service may be slow or unavailable.

Diagnostic steps: Check console for SocketTimeoutException and verify the player name or supported URL.

Fix: Wait for fetch completion, restore network access, or execute /menpc setskin <id> <player-name|url> again.

Verification: Re-log or respawn the NPC; cached skin data should apply.

Escalation: Include the input type, timestamp, and relevant timeout without exposing credentials.

Interactions

Symptoms: Clicking NPC does nothing.

Likely causes: Cooldown is active, click type is disabled, action is malformed, or permission is missing.

Diagnostic steps: Check default-interaction-cooldown, click enablement, /menpc interaction <id> <clickType>, and actor permissions.

Fix: Enable intended click type, wait for cooldown, use a supported action prefix, and grant modelenginenpc.command.interaction when appropriate.

Verification: Test with a non-privileged account and confirm expected message or command result.

Escalation: Include click type, action prefix, and sanitized command text.

Animations and LookClose

Symptoms: Animation does not play, or NPC does not look at nearby players.

Likely causes: Animation name is absent from ModelEngine data; player is outside LookClose radius; v2.0.1 runtime evidence is still pending.

Diagnostic steps: Verify model animation name, run /menpc play <id> <anim>, and test inside and outside configured radius.

Fix: Use an existing animation name and a supported LookClose radius.

Verification: Observe idle/interaction animation and orientation from multiple distances.

Escalation: Include model ID, animation name, radius, and console output.

Holograms

Symptoms: Hologram commands fail or no text appears.

Likely causes: FancyHolograms is not installed or enabled.

Diagnostic steps: Check /plugins and startup log, then confirm hologram configuration.

Fix: Install FancyHolograms 2.10.0+ and restart cleanly.

Verification: Run /menpc hologram <id> enable and confirm text appears.

Escalation: Include FancyHolograms version and first hologram error.

Storage and Restart

Symptoms: NPC changes disappear or startup fails after manual edits.

Likely causes: npcs.yml or config was edited while server was running, invalid YAML was saved, or /reload left stale state.

Diagnostic steps: Stop server, validate recent file changes, and compare with backup.

Fix: Restore a known-good backup, edit only while stopped, then perform a clean restart.

Verification: /menpc list shows expected NPCs and entities spawn correctly.

Escalation: Include sanitized YAML error and backup timestamp.

FAQ

Do I need ModelEngine installed if I only want player NPCs?

ModelEngine is declared as a required dependency in plugin metadata. Install ModelEngine and PacketEvents to start plugin cleanly.

Can normal NPCs use skins from URLs?

Yes, pass a supported skin URL to /menpc setskin. External fetch is asynchronous.

Does ModelEngineNPC support /reload?

No. Stop the server completely, replace or configure files, then start the server again.

Changelog

2.0.0 (Source baseline)

• Hardened persistence lifecycle.
• Runtime tested on Paper 26.2 build 124.
• Native NPC integration with PacketEvents.
• Security checks for console interaction commands.

2.0.1 (Target release)

Final release notes pending official v2.0.1 tag and artifact. Technical pages remain in review until release artifact is verified.

Support

Before opening a support request:

1. Read this troubleshooting guide.
2. Confirm server version is supported in Compatibility.
3. Gather server log showing plugin startup and error trace.
4. Note Minecraft, Paper, ModelEngine, and PacketEvents versions.

Submit reports through official Minekarta support channels with log excerpt and reproduction steps. Do not include passwords or sensitive tokens.