[{"data":1,"prerenderedAt":314},["ShallowReactive",2],{"docs-\u002Ffaq":3},{"id":4,"title":5,"body":6,"description":304,"extension":305,"meta":306,"navTitle":307,"navigation":308,"path":309,"rawbody":310,"seo":311,"stem":312,"__hash__":313},"docs\u002Ffaq.md","FAQ \u002F Troubleshooting",{"type":7,"value":8,"toc":283},"minimark",[9,13,17,22,34,48,51,58,73,79,94,101,111,115,118,150,154,157,185,188,192,199,207,214,221,228,238,241,263,266,270],[10,11,5],"h1",{"id":12},"faq-troubleshooting",[14,15,16],"p",{},"Common issues and fixes when integrating MagicUtils.",[18,19,21],"h2",{"id":20},"yamltoml-config-not-available","YAML\u002FTOML config not available",[14,23,24,25,29,30,33],{},"If you see ",[26,27,28],"code",{},"YAMLFactory","\u002F",[26,31,32],{},"TOMLFactory"," missing, add the format helpers:",[35,36,37,43],"ul",{},[38,39,40],"li",{},[26,41,42],{},"magicutils-config-yaml",[38,44,45],{},[26,46,47],{},"magicutils-config-toml",[14,49,50],{},"If the config format is not required, switch to JSON\u002FJSONC instead.",[18,52,54,55],{"id":53},"jackson-nosuchmethoderror","Jackson ",[26,56,57],{},"NoSuchMethodError",[14,59,60,61,64,65,68,69,72],{},"Errors like ",[26,62,63],{},"YAMLParser.createChildObjectContext(...)"," or\n",[26,66,67],{},"BufferRecycler.releaseToPool()"," indicate mixed Jackson versions. Make sure\nyour project uses the same Jackson version as MagicUtils (currently ",[26,70,71],{},"2.17.1",")\nand exclude older transitive Jackson artifacts.",[18,74,76],{"id":75},"noclassdeffounderror-devuatheroermagicutilsplatformplatform",[26,77,78],{},"NoClassDefFoundError: dev.ua.theroer.magicutils.platform.Platform",[14,80,81,82,85,86,89,90,93],{},"The platform API is missing from the runtime. Add ",[26,83,84],{},"magicutils-api"," (or use a\nplatform bundle such as ",[26,87,88],{},"magicutils-bukkit"," \u002F ",[26,91,92],{},"magicutils-fabric-bundle",").",[18,95,97,100],{"id":96},"noclassdeffounderror-for-adventure-classes",[26,98,99],{},"NoClassDefFoundError"," for Adventure classes",[14,102,103,104,64,107,110],{},"Missing classes like ",[26,105,106],{},"net.kyori.ansi.StyleOps",[26,108,109],{},"net.kyori.adventure.text.serializer.json.JSONComponentSerializer"," mean the\nAdventure serializer dependencies were not included. Use the platform bundle\nor add the required Adventure modules explicitly.",[18,112,114],{"id":113},"placeholders-do-not-resolve","Placeholders do not resolve",[14,116,117],{},"MagicUtils bridges to external placeholder mods\u002Fplugins only when they are\ninstalled:",[35,119,120,130,138],{},[38,121,122,123],{},"Bukkit: ",[124,125,129],"a",{"href":126,"rel":127},"https:\u002F\u002Fmodrinth.com\u002Fplugin\u002Fplaceholderapi",[128],"nofollow","PlaceholderAPI",[38,131,132,133],{},"Fabric: ",[124,134,137],{"href":135,"rel":136},"https:\u002F\u002Fplaceholders.pb4.eu\u002F",[128],"PB4 Placeholder API",[38,139,132,140,64,145],{},[124,141,144],{"href":142,"rel":143},"https:\u002F\u002Fmodrinth.com\u002Fmod\u002Fplaceholder-api",[128],"Text Placeholder API",[124,146,149],{"href":147,"rel":148},"https:\u002F\u002Fmodrinth.com\u002Fmod\u002Fminiplaceholders",[128],"MiniPlaceholders",[18,151,153],{"id":152},"which-artifact-should-i-use","Which artifact should I use?",[14,155,156],{},"For most users:",[35,158,159,164,169,175],{},[38,160,161,162],{},"Bukkit\u002FPaper plugin: ",[26,163,88],{},[38,165,166,167],{},"Fabric mod: ",[26,168,92],{},[38,170,171,172],{},"Velocity plugin: ",[26,173,174],{},"magicutils-velocity",[38,176,177,178,181,182],{},"NeoForge mod: ",[26,179,180],{},"magicutils-neoforge"," plus ",[26,183,184],{},"magicutils-commands-neoforge",[14,186,187],{},"Use the modular artifacts only when you intentionally want custom wiring.",[18,189,191],{"id":190},"permissions-on-fabric","Permissions on Fabric",[14,193,194,195,198],{},"Without ",[26,196,197],{},"fabric-permissions-api",", MagicUtils falls back to op-level checks.\nInstall the permissions API (and a permissions plugin like LuckPerms) to get\nfull permission support.",[18,200,202,203,206],{"id":201},"do-i-need-to-call-magicruntimeclose","Do I need to call ",[26,204,205],{},"magic.runtime().close()","?",[14,208,209,210,213],{},"Yes, if you built your services through ",[26,211,212],{},"buildRuntime()"," and your platform has a\nclear shutdown phase. Closing the runtime unregisters hooks, closes managed\nresources, and shuts down the config manager when it owns it.",[18,215,217,218,206],{"id":216},"why-do-fabric-commands-still-register-in-commandregistrationcallback","Why do Fabric commands still register in ",[26,219,220],{},"CommandRegistrationCallback",[14,222,223,224,227],{},"Because Brigadier registration still belongs to Fabric's command callback.\n",[26,225,226],{},"FabricBootstrap"," prepares the shared services and command registry, but the\ndispatcher itself only exists inside the event callback.",[18,229,231,234,235,206],{"id":230},"logger-or-loggercore",[26,232,233],{},"Logger"," or ",[26,236,237],{},"LoggerCore",[14,239,240],{},"Use:",[35,242,243,258],{},[38,244,245,247,248,250,251,254,255,257],{},[26,246,233],{}," on Bukkit, Fabric, and NeoForge (bootstrap returns the ",[26,249,233],{},"\nwrapper; ",[26,252,253],{},"Logger.getCore()"," gives you the underlying ",[26,256,237],{},")",[38,259,260,262],{},[26,261,237],{}," on Velocity and custom platforms",[14,264,265],{},"Bootstrap helpers return the correct logger type for each platform.",[18,267,269],{"id":268},"config-watcher-warnings","Config watcher warnings",[14,271,24,272,89,275,278,279,282],{},[26,273,274],{},"Failed to register config watcher",[26,276,277],{},"inotify"," warnings, your OS\nfile watch limit is too low. MagicUtils disables realtime reload in this\ncase. Increase the limit or call ",[26,280,281],{},"ConfigManager.shutdown()"," on plugin disable\nto free watchers.",{"title":284,"searchDepth":285,"depth":285,"links":286},"",3,[287,289,291,292,294,295,296,297,299,301,303],{"id":20,"depth":288,"text":21},2,{"id":53,"depth":288,"text":290},"Jackson NoSuchMethodError",{"id":75,"depth":288,"text":78},{"id":96,"depth":288,"text":293},"NoClassDefFoundError for Adventure classes",{"id":113,"depth":288,"text":114},{"id":152,"depth":288,"text":153},{"id":190,"depth":288,"text":191},{"id":201,"depth":288,"text":298},"Do I need to call magic.runtime().close()?",{"id":216,"depth":288,"text":300},"Why do Fabric commands still register in CommandRegistrationCallback?",{"id":230,"depth":288,"text":302},"Logger or LoggerCore?",{"id":268,"depth":288,"text":269},"Answers to common MagicUtils questions and fixes for setup, bootstrap, config, command, and platform issues across Bukkit, BungeeCord, Velocity, Fabric, and NeoForge.","md",{},null,true,"\u002Ffaq","---\ndescription: Answers to common MagicUtils questions and fixes for setup, bootstrap, config, command, and platform issues across Bukkit, BungeeCord, Velocity, Fabric, and NeoForge.\n---\n\n# FAQ \u002F Troubleshooting\n\nCommon issues and fixes when integrating MagicUtils.\n\n## YAML\u002FTOML config not available\n\nIf you see `YAMLFactory`\u002F`TOMLFactory` missing, add the format helpers:\n\n- `magicutils-config-yaml`\n- `magicutils-config-toml`\n\nIf the config format is not required, switch to JSON\u002FJSONC instead.\n\n## Jackson `NoSuchMethodError`\n\nErrors like `YAMLParser.createChildObjectContext(...)` or\n`BufferRecycler.releaseToPool()` indicate mixed Jackson versions. Make sure\nyour project uses the same Jackson version as MagicUtils (currently `2.17.1`)\nand exclude older transitive Jackson artifacts.\n\n## `NoClassDefFoundError: dev.ua.theroer.magicutils.platform.Platform`\n\nThe platform API is missing from the runtime. Add `magicutils-api` (or use a\nplatform bundle such as `magicutils-bukkit` \u002F `magicutils-fabric-bundle`).\n\n## `NoClassDefFoundError` for Adventure classes\n\nMissing classes like `net.kyori.ansi.StyleOps` or\n`net.kyori.adventure.text.serializer.json.JSONComponentSerializer` mean the\nAdventure serializer dependencies were not included. Use the platform bundle\nor add the required Adventure modules explicitly.\n\n## Placeholders do not resolve\n\nMagicUtils bridges to external placeholder mods\u002Fplugins only when they are\ninstalled:\n\n- Bukkit: [PlaceholderAPI](https:\u002F\u002Fmodrinth.com\u002Fplugin\u002Fplaceholderapi)\n- Fabric: [PB4 Placeholder API](https:\u002F\u002Fplaceholders.pb4.eu\u002F)\n- Fabric: [Text Placeholder API](https:\u002F\u002Fmodrinth.com\u002Fmod\u002Fplaceholder-api) or\n  [MiniPlaceholders](https:\u002F\u002Fmodrinth.com\u002Fmod\u002Fminiplaceholders)\n\n## Which artifact should I use?\n\nFor most users:\n\n- Bukkit\u002FPaper plugin: `magicutils-bukkit`\n- Fabric mod: `magicutils-fabric-bundle`\n- Velocity plugin: `magicutils-velocity`\n- NeoForge mod: `magicutils-neoforge` plus `magicutils-commands-neoforge`\n\nUse the modular artifacts only when you intentionally want custom wiring.\n\n## Permissions on Fabric\n\nWithout `fabric-permissions-api`, MagicUtils falls back to op-level checks.\nInstall the permissions API (and a permissions plugin like LuckPerms) to get\nfull permission support.\n\n## Do I need to call `magic.runtime().close()`?\n\nYes, if you built your services through `buildRuntime()` and your platform has a\nclear shutdown phase. Closing the runtime unregisters hooks, closes managed\nresources, and shuts down the config manager when it owns it.\n\n## Why do Fabric commands still register in `CommandRegistrationCallback`?\n\nBecause Brigadier registration still belongs to Fabric's command callback.\n`FabricBootstrap` prepares the shared services and command registry, but the\ndispatcher itself only exists inside the event callback.\n\n## `Logger` or `LoggerCore`?\n\nUse:\n\n- `Logger` on Bukkit, Fabric, and NeoForge (bootstrap returns the `Logger`\n  wrapper; `Logger.getCore()` gives you the underlying `LoggerCore`)\n- `LoggerCore` on Velocity and custom platforms\n\nBootstrap helpers return the correct logger type for each platform.\n\n## Config watcher warnings\n\nIf you see `Failed to register config watcher` \u002F `inotify` warnings, your OS\nfile watch limit is too low. MagicUtils disables realtime reload in this\ncase. Increase the limit or call `ConfigManager.shutdown()` on plugin disable\nto free watchers.\n",{"title":5,"description":304},"faq","NrUfXSprWwNuaMbxKxtIG8hhSOPpzSypjUQp-2kDOss",1783944487404]