Skip to Content
TroubleshootingLoading errors

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.json at the zip root (e.g. the folder was zipped with an extra nesting level)
  • Check: open the zip — pack.json at the top level (or directly under one common root folder)
  • Fix: zip pack.json and the .wgsl files 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.json files (including case differences)
  • Fix: keep exactly one

Size & count limits

MessageLimit
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 .wgsl files / 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

IDMeaning
loadZipTooBigzip over 32MB
loadTooManyZipEntriesover 1024 entries
loadTooManyWgslover 256 .wgsl
loadSourceTooBigover 256KB total (streamed per-file check)
loadManifestTooBigpack.json over 64KB
loadManifestNotJson / loadManifestNotObjectnot JSON / not an object
loadNoApiVersion / loadWrongApiVersionmissing / not 5 (API version errors)
loadNoName / loadAuthorNotStringmissing name / non-string author
loadUnsupportedCompression / loadZip64 / loadSplitZip / loadEncryptedunsupported compression / zip64 / split / encrypted
loadDuplicatePath / loadNotUtf8 / loadDecompressFailed / loadZipDamagedduplicate path / non-UTF-8 / decompress failure / damaged zip
loadNoManifest / loadDuplicateManifestmanifest 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=, localStorage bloxdRenderer) make packs refuse to start — clear them and reload