Previous: Item Source References　·　Next: Overview (External Plugin Integration)

🩺 Diagnostics & Troubleshooting

/qcl status is the first stop for troubleshooting any problem. This page walks through its output line by line, provides a health-code table, gives remedies for common problems, and includes a "troubleshooting decision tree".

🔐 Command permission: /qcl status requires qcl.status, alias /qcl probe; the detailed version /qcl status detail (alias /qcl status full). See Commands & Permissions.

---

🟢 Health-Code Table

The diagnostic output is full of "health codes". Common values:

Health Code	Meaning	Action Needed
OK	Normal	✅ No action needed
NO_HOOK	No corresponding soft dependency (external plugin not installed)	⚪ Normal situation, install as needed
DEGRADED	Degraded, but recoverable	⚠️ Attention; usually a missing/not-ready soft dependency

📌 NO_HOOK is not an error — it just means you haven't installed the corresponding external plugin, so the related integration is naturally not enabled.

---

📋 /qcl status Summary, Item by Item

The /qcl status summary contains the following items. The table below gives the meaning, normal value, and abnormal handling for each.

Diagnostic Item	Meaning	Normal Appearance	What to Do if Abnormal
Soft Dependency Probe · Item Source	Number of registered item sources + list	Lists the sources for the item plugins you installed	Source missing → install the corresponding plugin + confirm the module is not disabled
Soft Dependency Probe · Economy	Detected economy plugin	Shows Vault/EE/PlayerPoints	Economy missing → install an economy plugin
Soft Dependency Probe · Attribute Plugin	Detected attribute plugin	Shown according to what you installed	—
Soft Dependency Probe · Hooked Plugins	List of hooked external plugins	Lists hooked items	—
Platform Status	Whether the overall platform is normal	Normal	Abnormal → check health code/suggestions
Health Code	Platform health code	OK	DEGRADED → follow the health suggestion
Health Suggestion	Repair suggestion given by the platform	None/hint	Follow the suggestion
Module Health Code	Overall module health	OK	Use detail to see which module
Script Bridge	Whether the script bridge is available + number of loaded scripts	Available	Unavailable → see below
Economy Bridge Health Code	Economy bridge health	OK	NO_HOOK/DEGRADED → see below
PAPI Bridge Health Code	PlaceholderAPI bridge health	OK/NO_HOOK	Install PAPI
Database Health Code	Database bridge health	OK	Check the database section of config.yml
PDC Health Code	PDC storage health	OK	—
QI/QS/QF/QSt Status	Status of each sub-plugin and their bridge/protocol counts	Shown according to installed sub-plugins	Sub-plugin not installed → not shown/unavailable
Config Diagnostic Code	Config loading diagnostics	OK	Check config.yml syntax
API Boundary Code	API boundary check	OK	See reference diagnostic codes
Public API Count / apiJar Package Count / Internal Package Count	API statistics	Number	Generally no need to pay attention
apiJar Diagnostic Code / Exportable API Class Count	API jar diagnostics	OK / Number	See reference diagnostic codes
Startup Diagnostic Code	Startup-flow diagnostics	OK	Check the startup log
Item Reference Diagnostic Code	Live-tests resolving vanilla:stone	OK	Item module abnormal → check modules.item

---

🔬 /qcl status detail Extra Items

The detailed version outputs the following on top of the summary:

• Bridge Count, Module Count, TraceId (include it when reporting issues to aid locating).
• Per module: each module shows "Enabled/Not Enabled" + "Available/Unavailable" + message.
• Per bridge: each bridge shows "Enabled/Not Enabled" + "Available/Unavailable" + Source + message.
• Script extension lines: custom lines appended by the script global:qcl_status.js:formatStatus.

💡 "Enabled/Not Enabled" is determined by the modules switches in config.yml; "Available/Unavailable" is determined by whether the soft dependency is ready. The two have different meanings — keep them distinct when troubleshooting.

---

🧰 Common Troubleshooting

❓ A bridge shows "Unavailable"

1. First run /qcl status detail to see the bridge's "Enabled/Not Enabled".
   • Not Enabled → the modules section in config.yml has disabled the corresponding module; set it back to true and restart.
   • Enabled but Unavailable → check the bridge's "Source" and "Message"; usually the corresponding external plugin is not installed/version mismatched/not ready.
2. If the health code is NO_HOOK → normal, just install the corresponding soft dependency.
3. If the health code is DEGRADED → follow the "Health Suggestion" in the summary.

❓ Script bridge unavailable

• Check whether javascript.enabled in config.yml is true.
• Check whether modules.script is true.
• Enable javascript.debug.print-stacktrace: true, then after /qcl reload check the console for the error stack trace.
• Confirm the script path format is correct: namespace:relative-path.js[:function-name].

❓ Economy bridge unavailable / NO_HOOK

• NO_HOOK means no economy plugin was detected → install one of Vault / ExcellentEconomy / PlayerPoints.
• Still unavailable after installing → check whether economy.default-provider specifies a provider that is not installed; set it back to auto to let it pick automatically.
• When using EE with multiple currencies, confirm economy.default-currency is a valid EE currency id.

❓ An item reference fails

Treat by error code (see Item Source References for details):

Error Code	Handling
PARSE_FAILED	Check the reference format (separators, segment count)
MATERIAL_NOT_FOUND	Verify the vanilla material name (all-uppercase enum)
SOURCE_NOT_FOUND	Corresponding plugin not installed / module disabled
ITEM_NOT_FOUND	Item id misspelled / the item is not configured

First check whether the "Item Reference Diagnostic Code" at the end of /qcl status is OK (it live-tests vanilla:stone); if even vanilla doesn't work, modules.item is most likely disabled.

❓ Module not enabled

In /qcl status detail, a module shows "Not Enabled" → go to the modules section of config.yml and set it back to true, then restart the server (module switches affect loading; reload is not enough).

---

🌲 Troubleshooting Decision Tree

A feature is malfunctioning?
│
├─ Related item shows "Not Enabled" in /qcl status detail?
│     └─ Yes → set config.yml modules back to true → restart
│
├─ Shows "Unavailable"?
│     ├─ Health code NO_HOOK → install the corresponding external plugin (normal situation)
│     ├─ Health code DEGRADED → follow the "Health Suggestion"
│     └─ Check "Source" and "Message" → usually external plugin not installed/version mismatched
│
├─ Item reference fails?
│     ├─ PARSE_FAILED      → fix the reference format
│     ├─ MATERIAL_NOT_FOUND→ fix the vanilla material name
│     ├─ SOURCE_NOT_FOUND  → install the plugin / enable the module
│     └─ ITEM_NOT_FOUND    → fix the item id
│
├─ Config change has no effect?
│     ├─ database / modules → must restart
│     └─ Others → /qcl reload
│
└─ Still stuck?
      └─ Screenshot /qcl status detail (with TraceId) → check ../05-参考/诊断码.md / FAQ.md

---

📖 Continue Reading

• 🔢 Diagnostic Codes — Meaning of all diagnostic/error codes
• ❓ FAQ — Quick answers to common questions
• ⚙️ Config Files — Reload vs restart boundary, module switches
• 🕹️ Commands & Permissions — /qcl status / reload usage
• 🎯 Item Source References — Item reference error codes explained