Loading errors
Target API: 5 · Status: Verified
Errors rejected at the loader stage (the first gate), shown in the settings status line with shaderPack:load* IDs.
“There’s no pack.json at the top of the pack.”
- Cause: no
pack.jsonat the zip root (e.g. the folder was zipped with an extra nesting level) - Check: open the zip —
pack.jsonat the top level (or directly under one common root folder) - Fix: zip
pack.jsonand the.wgslfiles directly. A single common root folder is stripped automatically (Pack structure) - Prevention: keep your zipping procedure fixed; macOS “Compress” works as-is (OS junk is auto-excluded)
loadDuplicateManifest on zip load
- Cause: two
pack.jsonfiles (including case differences) - Fix: keep exactly one
Size & count limits
| Message | Limit |
|---|---|
The zip is over 32 MB. | zip 32 MB |
The zip has more than 1024 entries. | 1,024 entries |
The pack has more than 256 .wgsl files. | 256 .wgsl files |
The pack's .wgsl files are over 256 KB in total. | 256 KB total |
pack.json is over 64 KB. | 64 KB manifest |
- Fix: drop unneeded
.wgslfiles / merge files / trim comments - Prevention: these limits are also practical compile-time ceilings — treat growth as a refactoring signal
Format problems
Split zips, zip64, encrypted entries and unsupported compression are each rejected with dedicated messages. All files must be valid UTF-8.
Loader error-ID reference
| ID | Meaning |
|---|---|
loadZipTooBig | zip over 32MB |
loadTooManyZipEntries | over 1024 entries |
loadTooManyWgsl | over 256 .wgsl |
loadSourceTooBig | over 256KB total (streamed per-file check) |
loadManifestTooBig | pack.json over 64KB |
loadManifestNotJson / loadManifestNotObject | not JSON / not an object |
loadNoApiVersion / loadWrongApiVersion | missing / not 5 (API version errors) |
loadNoName / loadAuthorNotString | missing name / non-string author |
loadUnsupportedCompression / loadZip64 / loadSplitZip / loadEncrypted | unsupported compression / zip64 / split / encrypted |
loadDuplicatePath / loadNotUtf8 / loadDecompressFailed / loadZipDamaged | duplicate path / non-UTF-8 / decompress failure / damaged zip |
loadNoManifest / loadDuplicateManifest | manifest position / duplication |
“Ready. Reload the page to use it.” but nothing changes
- Cause: packs need a page reload to activate
- Fix: reload after selecting; status should become
Ready to use - Note: leftover renderer overrides (
?renderer=, localStoragebloxdRenderer) make packs refuse to start — clear them and reload