Troubleshooting

When something isn’t working as expected, use the guide below to pinpoint and resolve issues quickly.

1. YAML & Configuration Errors

Symptoms

• Plugin fails to load on startup

• /coreitems reload prints “Invalid YAML” or stack traces

Solutions

• Lint your YAML: Run customs.yml and config.yml through an online YAML linter to catch indentation or syntax mistakes.

• Compare example: Verify each item entry matches the Basic Item Format (material, name, etc.).

• Check console: Error messages will usually indicate the file and line number of the problem. Fix the typo and reload.

---

2. Items Not Appearing

Symptoms

• /coreitems list shows no items or misses certain entries

• /coreitems menu GUI is empty

Solutions

• Namespace folder: Ensure every namespace directory exists under plugins/CoreItems/customs/ and contains a customs.yml.

• Default namespace: If you omit the namespace in commands, CoreItems uses the default-namespace from config.yml. Make sure that folder has items.

• Reload: After creating or editing customs.yml, run /coreitems reload and watch for “Loaded X items” in console.

---

3. GUI Issues

Symptoms

• GUI doesn’t open or immediately closes

• Pagination arrows or icons missing

Solutions

• Enable GUI: Confirm gui.enabled: true in config.yml.

• Page sizes: Check gui.namespaces-per-page and gui.items-per-page aren’t set to zero.

• Border item: If you’ve set gui.border-item: NONE, empty slots will remain blank; consider using a neutral pane to help navigation.

• Console warnings: Look for “Failed to build menu” errors which often point to misconfigured titles or invalid material names.

---

4. Command Problems

Symptoms

• Typing /coreitems returns “Unknown command”

• Sub-commands (give, reload, list, menu) don’t execute

Solutions

• Plugin loaded?: On server startup, check for “[CoreItems] vX.Y.Z loaded successfully.” If absent, the JAR may be misplaced or incompatible with your server version.

• Main command: Verify commands.main-command and aliases in config.yml match what you’re typing.

• Permissions: Make sure the user has the appropriate node (coreitems.command.* or specific sub-command nodes).

---

5. Texture & Model Problems

Symptoms

• Items show as default texture (no custom model)

• Players see a missing texture “purple-black checker”

Solutions

• Model ID match: Ensure custom-model-data in YAML matches the numeric ID in your resource pack’s JSON file.

• Pack version: Push an updated resource pack and have players re-download or clear their cache.

• Server restart: Sometimes clients cache old models until reconnect or restart.

---

6. Performance & Errors on Use

Symptoms

• Server TPS drops when items are clicked

• Errors appear when item-bound commands run

Solutions

• Cooldowns: Increase item-interactions.global-cooldown or per-item cooldown to throttle heavy commands.

• Heavy actions: Avoid spawning large particle effects or summoning multiple entities at once—split into smaller steps or use longer cooldowns.

• Debug mode: Temporarily set debug: true in config.yml to see detailed logs of every item interaction.

---

7. Debugging Tips

• Use Debug Logs: Enable debug to log detailed load and click events.

• Check Full Stack Traces: Server console will show exactly where an exception occurred.

• Isolate Changes: If a new item is causing errors, comment it out and reload to confirm.

• Community Support: When in doubt, share your customs.yml snippet and error log in our Discord #support channel for faster help.

---

Still having trouble? Join our Discord in #support. We’re here to help you get up and running smoothly!