Diagnostics and Troubleshooting
Previous: Built-in Skills and Examples · Next: Performance and Throttling
A troubleshooting handbook organized as "symptom → cause → fix." Find your case in the decision tree below first, then read the matching section.
🌳 Quick decision tree
| Symptom | Most likely cause | Jump to |
|---|---|---|
| QS isn't enabled at all | QinhCoreLib (hard dependency) not installed | §1 |
| The skill fires but produces only one chat message | MM has no same-named skill (that's a placeholder stub) | §2 |
| The item does nothing at all when pressed | Not unlocked / handler not registered / atom mismatch | §3 |
| Hint "on cooldown / insufficient resource / no usable target / condition not met" | A matching gate stopped it | §4 |
| Console floods with schema warnings | Skill fields don't match the graph file | §5 |
| The combo finisher just won't fire | finalize / window / require_state misconfigured | §6 |
| Want to know which pipeline step it's stuck at | Use debug: true to see the trace | §7 |
| Bridge / MM status in doubt | Use /qs protocol, /qs bridge | §8 |
1. QS isn't enabled
QinhCoreLib (QCL) is a hard dependency. Without it, QS won't enable and the console reports a missing dependency. Install QCL first, then confirm the server is 1.21.11+ and Java 25+.
2. Skill shows only a placeholder message
Symptom: the skill passes every gate but only sends a single [QinhSkills] skillName, with no particles / damage / movement.
Cause: MM has no same-named skill, so QS degrades to a placeholder stub.
Fix:
- Go to
plugins/MythicMobs/skills/and write an MM skill with the same name as the skill id (e.g.fire_wave); /mm reload;- If needed,
/qs reloadto sync the bridge.
Seeing the placeholder message is actually good news — it means the QS side is fully working, and only MM's presentation layer is missing.
3. Item does nothing when pressed
Check item by item:
| Checkpoint | Fix |
|---|---|
| Skill not unlocked | /qs unlock <skill> [player], or configure starter_skills / default_all |
| Handler not registered | QI not installed or loaded later than QS; after installing QI, /qs reload |
atom doesn't match trigger.primary | Falls back to the entry node (the skill still fires), but confirm the key mapping is as expected |
| Skill not loaded at all | /qs list to see whether the skill is in the list; if not, /qs reload |
To confirm whether "the press" got through, run
/qs cast <skill>directly to bypass the item and check the returned result code.
4. Stopped by a gate
Any of the hints below means a gate stopped it — just check the matching skill config:
| Hint | Check here |
|---|---|
§cSkill on cooldown … / §cCharges … | cooldown.base / charges / cooldown group |
§cInsufficient resource | placeholder resources like resource.mana |
§cNo usable target | target's range / filter / required |
§cCast conditions not met | the conditions: list (level / health / target type…) |
§cSkill conflict | conflict_groups |
§cThe current cast mode is unavailable | cast_mode (toggle state / channel in progress) |
Each hint maps one-to-one with a result code; see CastResult Result Codes.
5. schema warnings
If the console reports schema_issues during /qs reload, the skill definition's meta / trigger / state / graph / execution sections don't line up with the matching graph file:
trigger.primarymust be among thetriggersof the graph entry node;graph.entrymust point at a graph node id that really exists;state.requiredmust be a valid SkillState (IDLE, etc.).
Read the /qs reload log for the specific fields it names and align them one by one. Since 1.0.16, passive (type: passive) skills need not declare trigger.primary — the schema handles them as PASSIVE automatically.
6. Combo finisher won't fire
When the finisher won't fire, check the graph's combos section item by item:
| Checkpoint | Requirement |
|---|---|
finalize_skill | Must be a node id within this graph's nodes (not _id, nor a nonexistent name) |
window_ms | Too short and it times out back to IDLE before you finish the sequence, breaking the combo; increase it appropriately |
Follow-up node require_state | Follow-up nodes must be COMBO_WINDOW (entered only after a successful opener — this is what distinguishes opener / follow-up) |
inputs sequence | Must include the opening press and match the actual key TriggerType exactly |
See Server Owner's Guide → Graph and Combos.
7. Using debug to read the trace
Add debug: true to a skill and the console prints a staged trace that pinpoints exactly where it's stuck:
[QI] [EVENT] [PARSE] [ROUTE] [GATE] [EXEC] [POST] [FALLBACK]| Tag | Stage |
|---|---|
[EVENT] | Trigger event received |
[PARSE] | Input normalized into a payload |
[ROUTE] | Graph routing selects a node |
[GATE] | Gate validation (stuck here means stopped by a gate) |
[EXEC] | Handed to MM for execution |
[POST] | Post-processing (CD / resource deduction / post_js) |
[FALLBACK] | Fell back to the entry node |
[BYPASS] | ⚠️ Architectural-conflict warning — its appearance means there's a call bypassing the pipeline that needs attention |
debug: trueis for troubleshooting only; always turn it off in production (high-frequency passives will flood the log). See Performance and Throttling.
8. Bridge and protocol diagnostics
| Command | What it shows |
|---|---|
/qs protocol | Protocol id / version, required fields, bridge availability, MM availability, ready state, compatibility |
/qs bridge | bridgeId, whether the bridge is available, the skill id of the most recent request |
When MM is installed but skills don't execute, check these two commands first to confirm the bridge and MM are ready.
Read next
- CastResult Result Codes — Handling advice for each result code
- Message Copy Quick Reference — The original hint text for comparison
- Performance and Throttling — Passive flooding / lag
- FAQ — Quick answers to frequent questions