Validation Error Quick Reference (Troubleshooting)
Section: Reference · Related: Item Definition · Resource Pack · Layers & Assembly
When saving / reloading items, QI runs a full validation suite (PolicyEngine and the various validators). This page lists every possible error message verbatim, what triggers it, whether it is an error (blocks save) or a warning (allows save), and the fix.
Errors surface in: the
/qi reloadconsole, the GUI save prompt,/qi status//qi diagnose//qi problems.
1. Item Health Check (QinhItemDefinition.healthIssues)
Item structural integrity. All are errors (item is unhealthy, listed in the problem list).
| Error message | Cause | Fix |
|---|---|---|
id 为空 | Item ID is missing | Add the top-level key |
type 为空 | Type is missing | Add type, or confirm the file name is a valid type |
material 为空 | Material is missing | Add material |
sourceFile 为空 | Source file is lost (internal) | Save again |
缺少 displayName/lore | Neither name nor lore is present | Provide at least one of display_name or lore |
maxStackSize 非法 | options.max_stack_size ≤ 0 | Change to 1–99 |
configVersion 非法 | Version number ≤ 0 | Change update.version to a positive integer |
unknown type=$type | Type is not in item_types.yml | Use a valid type, see Item Types |
unknown material=$material | Material is not a valid Bukkit material | Use a valid vanilla material name or an external-source reference |
2. PolicyEngine (Overall Validation)
| Error message | Cause | Type |
|---|---|---|
变量键 '$key' 违反 ICVM 红线 | The variable key uses a semantically reserved word (see §8) | Error |
物品 $id ($sourceFile) 内联 actions 无法解析 | The inline actions block failed to parse (indentation / format error) | Error |
The most common cause of "inline actions cannot be parsed" is misaligned indentation: the
actionsblock must be at the same level asmaterial/type; being off by one space breaks the whole block.
3. Resource Pack Field Validation (ResourcePackValidator)
All are errors. See Resource Pack → Validation Constraints.
| Error message | Cause |
|---|---|
resource_pack.custom_model_data 不能为负数 ($cmd) | CMD < 0 |
resource_pack.model 不能为空字符串 | model is blank |
resource_pack.model 需 namespace:path 格式，got '$trimmed' | model is missing a namespace (no colon) |
resource_pack.model 不能含空格 | model contains a space |
resource_pack.model 禁止与状态/变量绑定 ($deny) | model contains a forbidden substring { } $ star tier layer |
resource_pack 含禁止字段 $forbidden — 仅允许 custom_model_data / model | resource_pack contains an illegal key |
resource_pack allows only two keys: custom_model_data, model.
4. Resource Pack Isolation Scan (ResourcePackReferenceScanner)
All are errors, prefixed with [RP_POLICY]. Design intent: the model appearance must be static and cannot vary with item state.
| Error message | Cause |
|---|---|
[RP_POLICY] ResourcePack cannot reference ICVM variables — $field: '...' | model contains { } % ${ or a variable reference |
[RP_POLICY] ResourcePack cannot bind layers — $field: '...' | model contains a layer token: layer/layers/patch/patch_pack/layerstack/write_domain/instance/runtime/compiled/compile_epoch |
[RP_POLICY] ResourcePack cannot depend on actions — $field: '...' | model contains an action token: action/actions/trigger/triggers/handler/refs/dispatch/cooldown/routing |
[RP_POLICY] ResourcePack cannot contain conditional rendering — $field: '...' | model contains a condition token: if/when/unless/condition/switch/random/weight |
5. Action Reference Validation (ActionRefDeclarationValidator)
| Error message | Cause | Type |
|---|---|---|
ActionTable id 不能为空 | The action table has no item ID | Error |
trigger '$trigger' 无 refs | The trigger has no handler configured | Warning |
trigger '$trigger' ref[$i] 缺少 handler | The ref is missing a handler | Error |
trigger '$trigger' ref[$i] handler 不能含空格 | The handler contains a space | Error |
trigger '$trigger' ref[$i] handler 建议使用 namespace:id 格式（如 qinhskills:cast） | The handler has no colon prefix | Warning |
trigger '$trigger' ref[$i] handler '...' — QinhSkills 未加载，runtime 将为 HANDLER_UNAVAILABLE | qinhskills:cast is used but QS is not installed | Warning |
trigger '$trigger' ref[$i] handler '...' 未注册 — runtime 将为 HANDLER_UNAVAILABLE | The handler is not registered | Warning |
Warnings do not block saving, but at runtime that handler will return
HANDLER_UNAVAILABLE. For the handler list, see Handlers.
6. Provider Validation (ProviderDeclarationValidator)
All are errors.
| Error message | Cause |
|---|---|
providers.$id 含非载体键 $illegal — 仅允许 [value, raw, data, payload] | The provider used an illegal payload key |
providers.$id 载荷为空 | The provider payload is empty |
Allowed payload keys: value / raw / data / payload. See Providers & Bridges.
7. Action Routing Red Lines (ActionRoutingPolicy)
| Error message | Cause | Type |
|---|---|---|
[QinhItems] Action 路由红线: trigger '$trigger' 禁止字段 $forbidden — 只允许 trigger→refs/cooldown/conditions；复杂流程(if/else/when/switch…)请放 Handler 内 | A trigger contains a logic field | strict: true blocks, false only warns |
Forbidden fields (FORBIDDEN_TRIGGER_KEYS): if else when unless switch match filter require rules flow chain pipeline logic tree variables layer providers priority weight random
For complex logic, develop a handler.
8. Layer Semantic Red Lines (LayerSemanticGuard)
Variable keys may not reuse "combat semantic" reserved words (to prevent breaking balance).
| Error message | Cause |
|---|---|
[QinhItems] Layer 红线: 禁止语义变量键 '$key' ($context)。请用 star/quality 等状态键。 | The variable key hits the denylist |
[QinhItems] Layer 红线: 可疑语义键 '$key' ($context) | The variable key contains attack (except attack_count) |
Denylist (SEMANTIC_KEY_DENYLIST): attack_damage attack damage crit critical crit_rate crit_damage defense armor health hp mana mp physical_attack magic_attack element fire ice lightning skill skills ability abilities strength dexterity intelligence vitality attack_speed movement_speed lifesteal
To express quality / star level, use state keys such as
star/quality; do not use attribute names as variable keys. Attributes should go throughproviders.ap.
9. Write-Domain Violations (WriteDomainPolicy)
strict: true (default) is an error, false is a warning. Three domains: INSTANCE / LAYER / RUNTIME, see Layers & Assembly → Write-Domain Policy.
| Error message | Cause |
|---|---|
runtime owner 不能为空 | The runtime-write owner is empty |
owner '$o' 保留给 instance 域（give/init）；runtime 请用 qi_admin / qi_ui / buff_* | A runtime write used an instance-reserved owner |
owner '$o' 属于 layer 系统域；请用 QinhItemsAPI.assembly().applyLayerPatch() | A runtime write used a layer-domain owner |
runtime override 只允许 UI/admin/临时 buff owner（如 qi_admin, qi_ui, buff_*） | The runtime owner does not match |
layer id / owner 不能为空 | A layer write is missing owner/id |
layer owner '$o' 不能来自 runtime 域（ui/admin/buff） | A layer used a runtime owner |
layer owner 不能使用 instance 保留 owner '$o' | A layer used an instance-reserved owner |
layer 只允许系统插件 owner/id（forge/gem/enchant/strengthen 等，见 write-domains.layer-owners） | The layer owner does not match |
Default owners / prefixes:
| Domain | owner | prefix |
|---|---|---|
| RUNTIME | qi_admin qi_ui admin | buff_ temp_ ui_ |
| LAYER | strengthen forge gem enchant socket refine embed upgrade | sys_ layer_ |
| INSTANCE reserved | qi_core give init template | — |
10. Troubleshooting Quick Reference: 8 Most Common Problems
- Actions have no effect / the whole block fails → misaligned indentation;
actionsmust be at the same level asmaterial; after fixing, run/qi reload. - A variable key trips a red line → don't use attribute names like
attack_damageas variable keys; usestar/quality. - resource_pack errors → only
custom_model_data/modelare allowed, andmodelcannot contain variables / layers / conditions. - provider errors → the payload key can only be
value/raw/data/payload, and must be non-empty. - handler warnings → use the
namespace:idformat;qinhskills:castrequires QinhSkills installed. - forbidden trigger fields → don't write if/switch in YAML; put logic in the handler.
- write-domain violations → when changing item state, be clear whether it is the instance / layer / runtime domain, and use the corresponding API.
- unknown type / material → look up the type in
item_types.yml, and use a valid vanilla name for the material.
Next Steps
- Item Definition: the correct syntax
- Resource Pack: model isolation rules
- Commands:
/qi diagnose//qi problems