-
Notifications
You must be signed in to change notification settings - Fork 0
Troubleshooting
Both widgets fail loudly. A mount that cannot succeed draws a dark panel into the container with the failing URL, the error, and a line or two on what to check, instead of leaving a blank box. This page maps what you see to what is wrong.
The bundle or a sprite could not be fetched, parsed, or used. The detail line names the cause.
The fetch was blocked or the host is unreachable. Nine times out of ten it is the first one.
The bundle is fetched by the page that runs the widget. For an iframe embed that page is embed.html on the embed host, not your page, so your bundle is always cross-origin there and always needs Access-Control-Allow-Origin. Check the response headers directly:
curl -I https://example.com/advancements/bundle.json
Your browser's network panel will also show the request as blocked, with the reason.
Serving the bundle from the same origin as the widget removes the problem entirely. See Self-hosting.
The URL is wrong. Open it in a browser tab and see.
Watch for relative paths: a relative bundle value resolves against embed.html on the embed host, not against your page. Use an absolute URL unless you are self-hosting.
The URL returned something that is not the bundle. A single-page-app host that answers every unknown path with index.html produces exactly this, and so does a 500 page served with a 200 status.
The widget cannot find its own textures. The window frame and the tooltip box are nine-sliced from those files before the first frame is drawn, so this fails the whole mount rather than degrading quietly.
By default the widget looks in the assets/ directory beside its own module, so the usual cause is that the two got separated. Running the widget through your own bundler does that, and so does copying viewer.js somewhere without its assets/. Set assetBase to wherever the assets ended up.
Sprites are loaded with crossOrigin="anonymous" so they can be cropped, which means an asset directory on another origin must send Access-Control-Allow-Origin. A self-hosted assets/ behind a server that omits the header produces this error too.
The bundle came from a different version of the preprocessor. Rebuild it with the version you are serving.
The file is a bundle but it is malformed, and the message names the offending entry. Rebuild rather than hand-editing. A bundle is generated output.
An item GUI bundle with several GUIs needs to be told which one. The message lists the valid ids. Set gui.
A name in items or itemsUrl is not in the bundle. Both messages list the valid names. Slot names come from the GUI definition and item names come from the item library, so check the bundle you are actually pointing at, not the one you last edited.
The items string must be slot=item pairs separated by commas. A slot or item name containing , or = must be percent-encoded.
Those squares are Minecraft's missing-texture texture, and they were baked into the bundle at build time. The preprocessor could not resolve an icon, warned about it, and wrote the placeholder rather than failing the build.
Custom items your datapack invents have no vanilla render, which is the usual cause. Give them one with --icon or --icon-map and rebuild. Rerun the build with warnings visible to see which ids failed.
Frames, tab sprites, and tab backgrounds are loaded as ordinary images and are not awaited, so one that 404s leaves a gap rather than failing the mount. Check that the whole assets/ directory is served, not just part of it.
The icon PNGs are not being served next to bundle.json. The bundle references them by relative path, so the whole output directory has to stay together.
If the icon was already a missing-texture square when you built the bundle, the preprocessor warned about it during the build. Rerun with warnings visible and read the output.
The default pixel font could not be loaded, so the browser substituted its own. The font is served from assetBase, or from coreAssetBase if you set one.
Unlike the textures, a missing font never fails the mount. The widget renders, measures, and lays out with whatever face the browser picked, so the result is legible and wrong rather than broken. That makes it worth checking the network panel rather than waiting for an error.
A font on another origin also needs cross-origin headers.
No translation is available for those keys. Either bake the strings into the bundle with --bake-lang, or serve a language file and point lang at it. Text and fonts covers both, and when each one is the right choice.
Advancements marked "hidden": true are not drawn until they are completed, which is what the game does. Turn on showHidden to draw the whole tree.
An advancement with no display is invisible by design, and its children reattach to the nearest visible ancestor. Check the datapack if a branch looks reparented.
Tabs are only drawn while there is room for them along the window's edges. A widget too small for the number of roots in your bundle silently drops the extras, exactly as the game does. Give the embed a larger box.
A root advancement with no display produces no tab at all. The preprocessor warns about that during the build.
The container is smaller than the widget's minimum. The advancement viewer needs 252 by 140 CSS pixels at scale 1, or 280 by 168 once the bundle has two or more tabs. The item GUI needs the size of its GUI texture.
A forced scale too large for the container does the same thing. Remove it, or use auto.
An element with no content has no height, and a widget in a zero-height box draws nothing. Set an explicit height in CSS. An iframe never grows to fit its contents either.
The error panel positions itself absolutely and fills its container. Without position: relative on the container it escapes to the nearest positioned ancestor, which can put it far from where you are looking. See Using the JavaScript API.
Check that the <script> tag has type="module". A bare <script> cannot use import.
The tree pans under the finger and hands the swipe back to the page once it runs out, so scrolling past it takes a second swipe. Inside a long article that is still annoying.
Set touchPan=page-first. The tree then never takes a vertical swipe. The cost is that one-finger vertical panning of the tree becomes unreachable. Horizontal swipes still pan.
--input must be a datapack root containing data/, or a folder with .json files in it. Nothing else is scanned. Check that the path is the directory you meant.
Unknown fields are rejected rather than ignored, which turns a typo that would have silently done nothing into a build failure. The message lists the fields that are valid there.
An advancement names a parent that is not in --input, or the parent links form a loop. The message lists every advancement involved with its file. Including a whole datapack rather than a subdirectory usually fixes the first one.
requirements must reference every criterion exactly once across its groups, and nothing else. The message lists what is missing and what is unknown. This is the game's own rule.
The build continues and the icon becomes a missing-texture square. Custom items your datapack invents have no vanilla render, so give them one with --icon or --icon-map. See Building advancement bundles.
Embedding
Reference
Building bundles
Running it yourself