Diagnostics & Troubleshooting Guide
Part of: Reference · Related: Validation Error Quick Reference · Commands
QI provides a set of diagnostic commands to help you locate problems. This page explains what each command outputs and how to read each metric.
1. Diagnostic Command Overview
| Command | Purpose |
|---|---|
/qi status | Brief load status (item count / problems / compile failures) |
/qi inspect | Detailed status inspection |
/qi diagnose | Full diagnostic report (subsystem availability) |
/qi problems | List all known problems |
/qi problems summary | Problem summary |
/qi trigger report | Action trigger configuration report |
2. How to Read the Startup Log
On startup / reload, QinhItemsStartupLog prints a summary:
Item definitions: 123 · ActionTable 45
Bridge: 3 · Layer: 4 · Handler: 12
Combat: enabled · Attribute backend: attributeplus (connected)
Gems: LI(LC✔·8 sockets) · MG(2 sockets)
Diagnostics: 30/30 items available| Line | Meaning | How to read |
|---|---|---|
| Item definitions / ActionTable | Number of loaded items, action tables | A noticeably low number → some files didn't load, check /qi problems |
| Bridge / Layer / Handler | Count of bridges, layer contributors, handlers | Handler should include qinhskills:cast (if QS is installed) |
| Combat | Combat module status | disabled (pure item library) = combat not enabled |
| Attribute backend | AP connection status | noop = AP not detected |
| Gems | Socket count for LI / MG backends | LC✔ = LegendCore bridge registered |
| Diagnostics | Available items / total items | Numerator ≠ denominator → some subsystem is abnormal |
3. /qi diagnose Report Items
Diagnose lists the health status of each entity one by one (ItemsDiagnostics):
| Report entity | Meaning | Attached hints |
|---|---|---|
QinhItem:<id> | Item definition health | type / quality / action file / config version |
ActionTable:<itemId> | Action table | binding count |
ActionTableProblem | Action load error | |
FailureFile:<kind> | YAML parse failure file | item / action |
ProviderBridge:<id> | Provider bridge | whether available |
ExternalResolver:<prefix> | External item resolver | |
LayerContributor:<namespace> | Layer contributor | order |
ActionHandler:<id> | Action handler |
The summary also provides: item / section / affix / action table counts, format and category per source, compile failures, reload problems, and grouped failure files.
4. Common Problem Diagnosis Flows
Problem: An item didn't load
1. /qi status → Check if "problems" count is > 0
2. /qi problems → Find the error for the corresponding item
3. Cross-reference Validation Error Quick Reference → Fix the YAML per the error
4. /qi reload → ReloadFor error meanings, see Validation Error Quick Reference.
Problem: Actions don't trigger
1. /qi trigger report → Confirm the item's trigger config is loaded
2. /qi trigger test <id> <player> → Manually execute the first trigger binding, check if it works
3. Check whether the trigger atom is appropriate (right_click on air may not fire, switch to left_click)
4. Check whether the handler is registered (use diagnose to view the ActionHandler list)
5. Remember /qi reload after editing YAML (actions only load on reload)Problem: Attributes not applied
1. Check "Attribute backend" in the startup log
· noop → AP not installed, or combat.enabled: false
· attributeplus → Normal
2. Check console for "mapping name does not exist" warnings → Edit attribute-mapping to align with AP
3. After equipping the item, use /qi refresh hand to force a refreshFor details, see Attributes & Values.
Problem: Gem sockets not recognized
1. Check the "Gems" line in the startup log: are the LI/MG backends enabled, is the socket count > 0
2. Verify the lore in integrations/legendinlay_sockets.yml matches LI's side character-for-character
3. LegendCore bridge: check the log for "checking LegendCore/groovy/QinhItemsModule.groovy"For details, see Integration Practice → Legendinlay.
5. Interpreting Health Metrics
An item is only considered healthy when its healthIssues() is empty. Unhealthy items still load but are listed as problems. For common causes of unhealthiness, see Validation Error Quick Reference §1.
The "N/M items available" in /qi diagnose: M is the total diagnostic items, N is the currently available items. The difference is the number of abnormal subsystems—go through each one to see which is unavailable.
6. Refresh-Related
Changed the config but old items on players didn't update? Use the refresh commands to re-render:
/qi refresh all # All online players
/qi refresh hand # Main hand only (fast for self-testing)Refresh = rebuild() + variables().refresh() on each QI item, preserving instance / seed. See Random Generation → Refresh Service.
Next Steps
- Validation Error Quick Reference: Each error + how to fix
- Commands: Diagnostic commands
- FAQ