Diagnostic Codes

Navigation: Documentation Home · Contents · Diagnostics & Troubleshooting · FAQ · Glossary · Module System

This page collects the status codes and error codes for each QinhCoreLib (QCL) subsystem, grouped by subsystem. Each code lists its meaning, the triggering scenario, and a handling suggestion.

These codes appear in three places:

Location	Who produces it	How you see it
The diagnostic lines of /qcl status / /qcl status detail	Each diagnostic checker (DiagnosticResult.code)	Run the command in-game or in the console
Developer API return values	ResolveResult.code (items), ScriptExecutionResult.code (scripts), EconomyTransactionResult.code (economy)	Read the return object in code
Console logs	Startup probe / each bridge	Server log file

---

🧱 Two-layer status: enabled vs available

Before reading codes, first understand the two-layer status QCL distinguishes for "modules" and "bridges" (/qcl status detail shows both):

Dimension	Field	Meaning	Determined by
Enabled / Not enabled	enabled	Whether this module/bridge is switched on	The modules.* toggles in config.yml + whether load()/enable() succeeded
Available / Unavailable	available	Whether it can actually work at runtime	Whether the corresponding soft dependency is installed and ready at runtime

A bridge can be "enabled but unavailable" (the toggle is on, but the corresponding plugin is not installed → NO_HOOK), or "not enabled" (turned off by modules.*). When troubleshooting, first figure out which layer you're at. See Module System for details.

---

❤️ Health codes (HealthReport / bridge status)

HealthReport.code, also the value shown under "health code / module health / each bridge health" in /qcl status.

Code	Meaning	Triggering scenario	Handling suggestion
OK	Normal	The module/bridge is hooked and running normally	No action needed
NO_HOOK	No soft-dependency hook	The corresponding external plugin is not installed; the bridge skips by design	This is normal graceful degradation; install the corresponding plugin when you need that capability
DEGRADED	Degraded (recoverable)	The corresponding plugin is installed but operation is impaired (API changes, version mismatch, etc.)	Check message / suggestion, then /qcl reload or restart after fixing

⚠️ NO_HOOK is not an error; it is the normal state of "the soft dependency is not installed". Only DEGRADED needs attention. On a brand-new server with no soft dependencies installed, it is completely normal for /qcl status to show many NO_HOOK entries.

---

📦 Item resolution codes (ItemSource)

Returned by item reference resolution via ItemSourceManager.parseItemReference; also the ResolveResult.code of the developer API ItemManagerAPI.resolve(...).

Code	Meaning	Triggering scenario	Handling suggestion
OK	Resolution succeeded	The reference is valid and the item has been built	No action needed
PARSE_FAILED	Reference string parse failed	Malformed reference format (empty string, illegal separator, etc.)	Verify the reference format, see Item Source References
MATERIAL_NOT_FOUND	Vanilla material not found	The vanilla: material name is misspelled or doesn't exist in this version	Check the spelling of the Material enum name (all uppercase)
SOURCE_NOT_FOUND	Item source not found	The source the reference points to is not registered (the corresponding plugin is not installed/enabled)	Install the corresponding item source plugin, or use a different source
MODULE_BUILD_FAILED	Module build failed	The item source module threw an error while building the item	Check the logs and verify whether the source's own configuration is valid
ITEM_NOT_FOUND	Item not found	This ID does not exist in that source	Verify whether the item ID actually exists in the corresponding source

🔎 The "item reference diagnostic" at the end of /qcl status uses vanilla:stone as a self-check—if it returns OK, the item source resolution chain itself is healthy. To troubleshoot a specific reference failure, use ItemManagerAPI.diagnose(ref, player) separately. See Item API for details.

---

📜 Script error codes (JavaScript / GraalVM)

ScriptExecutionResult.code, returned by script execution (GUI conditions/actions, API calls).

Code	Meaning	Triggering scenario	Handling suggestion
SCRIPT_UNAVAILABLE	Script subsystem unavailable	The GraalJS runtime is missing (usually plain Spigot didn't pull in the library), or javascript.enabled=false	Use Paper/Purpur; check config javascript.enabled
SCRIPT_PARSE_FAILED	Reference string parse failed	Malformed script reference format (not namespace:path.js[:functionName])	Fix the reference format
SCRIPT_NOT_FOUND	Script file not found	The specified script file does not exist	Verify the script's directory and path
SCRIPT_FUNCTION_MISSING	Function missing	The target function does not exist in the script	Check the function name, or config javascript.default-function
SCRIPT_FAILED	Execution failed	The script threw an exception at runtime	Enable javascript.debug.print-stacktrace to see the stack trace

See Scripting Quickstart and Script API for details.

---

💰 Economy codes (Economy)

EconomyTransactionResult.code, returned by economy operations (query/deposit/withdraw/set).

Code	Meaning	Triggering scenario	Handling suggestion
OK	Success	The economy operation completed	No action needed
CURRENCY_REQUIRED	A currency must be specified	Using ExcellentEconomy but no currency was specified and there is no default	Set economy.default-currency, or pass the currency explicitly in the call/action
INSUFFICIENT_FUNDS	Insufficient balance	The player doesn't have enough funds (common with take_money)	A normal business result; prompt the player as needed
NO_PROVIDER	No economy provider	No economy plugin is installed, or the specified provider is not registered	Install an economy plugin and configure economy.default-provider

EconomyDiagnostics (economy diagnostics)

Used by the economy bridge diagnostics of /qcl status and the developer diagnostic API.

Code	Meaning	Triggering scenario	Handling suggestion
ECONOMY_UNAVAILABLE	Economy unavailable overall	The economy subsystem has no usable backend	Check whether Vault/ExcellentEconomy/PlayerPoints is installed and enabled
ECONOMY_PROVIDER_MISSING	Provider missing	The specified provider is not registered	Verify economy.default-provider, or confirm that backend plugin is installed
ECONOMY_CURRENCY_MISSING	Currency missing	The specified/default currency does not exist in ExcellentEconomy	Configure economy.default-currency or verify the currency ID (money/silver/gold…)

See Economy Actions, Economy Plugins, and Economy API for details.

---

🧰 DiagnosticResult fields (developer)

All diagnostic results are carried uniformly in the DiagnosticResult<T> container; understanding the fields helps you read the status:

Field	Type	Meaning
success	Boolean	Whether this diagnostic succeeded
value	T?	The data attached to the diagnostic (e.g. the resolved item, the list of bridge statuses)
code	String	The status code (i.e. the codes in the tables above)
message	String	Human-readable message
source	String	The diagnostic source (module/bridge name)
recoverable	Boolean	Whether it is recoverable (DEGRADED-type is generally true)
suggestion	String	Fix suggestion
traceId	String	Trace ID, for correlating logs

Construct with the companion methods DiagnosticResult.ok(...) / DiagnosticResult.fail(...). See Module System · Diagnostic Model for details.

---

🕹️ Related commands

Command	Alias	Permission	Description
/qcl status	probe	qcl.status	Status summary
/qcl status detail	full	qcl.status	Full status (per-module/per-bridge + script extension lines)
/qcl reload	rl	qcl.admin	Reload config/economy/scripts/external item modules/GUI

---

Continue reading

• Diagnostics & Troubleshooting — Line-by-line reading of /qcl status and a troubleshooting decision tree
• FAQ — Frequently asked questions
• Module System · Diagnostic Model — DiagnosticResult / HealthReport / BridgeStatus
• Glossary — Term definitions
• Documentation Home · Contents