Errors reference
On this page
Every error code the SDK can show you, read from the source: what it means and how to fix it. The build and registry codes have a longer entry, with examples, in Troubleshooting.
Build errors
bizzpocket build (and dev, which builds on every save) prints CODE: message — see docs/theme-sdk/troubleshooting.md#code and exits 1. Several errors at once print as a numbered list. Defined in packages/cli/src/build/errors.ts.
| Code | Meaning | Fix |
|---|---|---|
NO_CONFIG |
The theme folder has no theme.config.ts (or .tsx/.mts/.js/.mjs). |
Create one, or run from the theme folder / pass --dir. |
NO_BLOCKS_DIR |
There is no blocks/ folder. |
Create blocks/ with one folder per block. |
NO_BLOCK_FILE |
A block folder has no block file. | Name it after the folder: blocks/x/x.tsx. |
AMBIGUOUS_BLOCK_FILE |
No <folder>.tsx and several other server .tsx files. |
Name the block file after the folder. |
NOT_A_BLOCK |
The block file does not export default block({...}). |
Export the block() definition as the default. |
INVALID_PACKAGE_JSON |
package.json is missing, or has no name/version. |
Add both (bizzpocket init creates them). |
PARSE_FAILED |
A source file has a syntax error. | Fix the file and line the message names. |
INVALID_BLOCK_NAME |
A block folder name is not lowercase-kebab. | Rename it: product_grid becomes product-grid. |
DUPLICATE_BLOCK_IDENT |
Two block folders give the same internal name (hero-2, hero2). |
Rename one. |
INVALID_THEME_ID |
The theme id (or the init folder name) is not lowercase-kebab. |
Use a name like my-theme. |
THEME_ID_MISMATCH |
id in theme.config.ts is not a plain string literal. |
Write theme({ id: 'my-theme', ... }). |
INVALID_MANIFEST |
The theme settings failed validation (path: reason per problem). |
Fix each listed path (version, layout names, tokens, styles). |
INVALID_LAYOUT_JSON |
A layouts/*.json file is not a JSON object. |
Fix the JSON (no comments, no trailing commas). |
UNKNOWN_LAYOUT_BLOCK |
A layout node's type names no block of the theme (the message gives the file and JSON path). |
Fix the type (the block folder name) or add the block. |
LAYOUT_PAGE_TYPE_MISMATCH |
A page layout's pageType is not its file name. |
Write the file name as pageType ("home" in home.json), or rename the file. |
UNRESOLVED_DEPENDENCY |
An import could not be resolved: a missing package or file, or a CLI-provided package missing from the CLI install. | bun add the package, fix the path, or reinstall the CLI. |
BUNDLE_FAILED |
The bundler could not build the code. | Fix the file and line in the first line of the message. |
CLIENT_IMPORT_FORBIDDEN |
A 'use client' file imports @bizzpocket/theme-sdk or zod. |
Keep those in the block file and pass the island plain data. |
NON_SERIALIZABLE_ISLAND_PROP |
A block passes a function, class instance or JSX element to a 'use client' component. |
Pass JSON data only; move the logic into the island. |
UNSUPPORTED_CLIENT_EXPORT |
A 'use client' file uses export * or a non-identifier export. |
Export each component by name. |
DUPLICATE_ISLAND |
Two island files of one block would get the same island id. | Rename one of them. |
UNSUPPORTED_OPTION |
The build was called (from code) with an out other than <theme>/dist. |
Drop the option. |
CSS_FAILED |
A CSS file has an unrecoverable error (file:line:column). |
Fix the CSS there. |
STYLES_EXPORT_MISSING |
package.json does not export ./styles. |
Add "exports": { "./styles": "./dist/styles.css" }. |
NO_GLOBAL_LAYOUT |
No layouts/global.json, and home.json has no header/footer to build one from. |
Add layouts/global.json with header and footer regions. |
INVALID_CATALOG |
The generated blocks.json failed validation (usually a bad category or role). |
Use an allowed category / role. |
UNKNOWN_DEFAULT_VARIANT |
defaultVariants names a variant no block of that type has. |
Use one of the listed variant ids. |
MIGRATE_INCOMPLETE |
bizzpocket migrate could not convert every 2.x variant, so it wrote nothing. |
Run --dry-run, fix the listed blocks, run again. |
CLIENT_HOOK_IN_SERVER |
Server code (the block or a module it imports) uses a browser-only API (useState, useEffect, @bizzpocket/theme/client...). |
Move the interactive part into a 'use client' file. |
GQL_NOT_A_QUERY |
A gql() document is a mutation or subscription, is unreadable, or is not a fixed string. |
Write one query document as a string constant; do writes from an island through the cart and account actions. |
INVALID_LOCALE |
A locale file or the i18n setting is invalid: a listed locales/<tag>.json is missing, too large or not one JSON object; a bad locale tag; a plural object without other; a message with HTML, a script URL or unbalanced braces; a key that is both a plain message and plural forms (the message names the file and key). |
Fix the file and key the message names. Messages are plain text with {placeholders}; write plurals as { "one": ..., "other": ... }. |
Registry errors
From bizzpocket add and bizzpocket diff, printed as CODE: message (exit 1). Defined in packages/cli/src/registry/source.ts.
| Code | Meaning | Fix |
|---|---|---|
REGISTRY_NOT_FOUND |
@bizzpocket/blocks could not be downloaded (address, access, network, or a withheld token). |
Check .npmrc and any "token withheld" warning above the error. |
UNKNOWN_ITEM |
add asked for an item the registry does not have. |
Check the name against Registry. |
MODIFIED_FILE |
add would overwrite a file you changed. |
See your changes with diff; replace with --overwrite. |
UNSAFE_PATH |
A file to write leaves the theme, goes through a symlink, or has a reserved name. | Replace the symlink with a folder; report a bad item name. |
INVALID_REGISTRY |
Malformed registry data, or an unsafe .npmrc (a ${VAR} other than the three allowed). |
Fix .npmrc; retry or report a broken package. |
NOT_INSTALLED |
diff <name> names an item this theme never installed. |
Run diff with no name, or add it first. |
INVALID_LOCK |
bizzpocket.json is not valid. |
Fix it, or delete it and re-run add. |
INVALID_FLAG |
A flag is wrong (e.g. --trust-registry without a bare host). |
Pass a host name only: --trust-registry registry.example.com. |
Why a block is runtime
A block whose data() is not a plain mapping of props and route values to helper calls is runtime: it runs data() itself on every request (one extra fetch round) instead of having its data fetched with the page. That is never wrong, only slower. bizzpocket build prints, per runtime block, <file>:<line> <what> [<reason>]; the reason is one of the size-report values below, and the build's text comes from the probe code. See Why is my block runtime?. Defined in packages/theme/src/needs.ts (RuntimeWhy) and packages/cli/src/build/report.ts.
Size-report reason
reason |
Meaning |
|---|---|
helper-not-imported |
data() calls something named like a helper that is not the real one imported from @bizzpocket/theme. |
data-not-static |
data() is not a plain mapping (the detail says what: a ternary, a computed value, a local constant...). |
load |
The block has load(). |
field-kind |
data() passes a prop whose field kind the server cannot coerce. |
renderer |
data() uses a helper only the renderer resolves (facets(), customer(), orders()...); the detail names it. Not a defect. |
Probe result (what the build saw when it ran data() with sample values)
| Code | Build says | Fix |
|---|---|---|
load |
the block has load() |
Intended: load() blocks always run per request. Use data() if the data does not depend on the shopper. |
source |
data() is not a plain mapping of props to helper calls |
Make data a plain arrow returning { name: helper({...}) } with props / route values passed straight through. |
inspected |
computed value: data() reads into, compares or computes on a prop or route value |
Do the computing in render, or pass the prop through unchanged. |
value |
computed value: a helper argument is not plain data (a function, an instance, NaN) |
Pass only strings, numbers, booleans, null, arrays and plain objects to helpers. |
varies |
what data() returns depends on the values passed in (a branch) |
Remove the branch; always return the same needs (a helper with an unset required argument resolves to null). |
not-a-need-map |
data() does not return a plain object of helper calls (async?) |
Return a plain object of helper calls; data may not be async. |
threw |
data() threw while the build ran it with sample values |
Make data total: it must not throw for any prop value. |
fallback |
menu() fallback must be a literal handle and handle must be an f.menu() prop |
Pass menu({ handle, fallback }) a literal fallback handle, and take handle from an f.menu() prop. |
field |
data() reads <kind> field "<prop>" (un-coercible kind), or a prop that is not a field, or a trait |
Pass a field kind the server can coerce (see Fields reference), or read the prop in render. |
renderer |
data() uses <helper>(), which only the renderer resolves |
Expected, not a defect: data() uses a helper only the renderer resolves (facets(), customer(), orders()...). The page costs one extra fetch, and is private when the helper reads shopper data. Move public needs to their own block if you want them cached. |
Block render errors
A block that throws while rendering never takes the page down. On the Bun runtime it becomes an empty <section data-block-type data-bp-error> and the message is logged without its stack (packages/theme-runtime/src/render.tsx). On the Next host the block boundary renders an empty, hidden marker; in development and preview builds its data-bp-error holds the error kind below, in production it is empty, and the kind goes only to the server log (packages/theme-sdk/src/block-boundary.tsx). Shoppers never see a kind or a message.
data-bp-error |
Code | Meaning |
|---|---|---|
missing-variant |
— | The layout names a block variant the theme does not have. |
props-validation |
— | Saved props failed the block's validation. |
loader-timeout |
BIZZ-002 | A single loader attempt exceeded its configured timeout. See BIZZ-014 for the all-retries-exhausted escalation. |
loader-rejected |
BIZZ-013 | The block loader rejected (upstream/network failure) with no dependsOn involved. Dependency failures are BIZZ-005. |
loader-output-validation |
BIZZ-003 | A loader payload or props object failed validation and no degrade policy applies. |
missing-capability |
BIZZ-001 | The host did not provide a capability the block requires. |
manifest-parse |
— | The theme manifest could not be read. |
theme-version-mismatch |
— | The theme targets an SDK / contract version the host does not support. |
theme-build |
— | The theme build artifact is missing or broken. |
unsupported-schema-version |
— | A layout's schemaVersion is not one the host reads. |
aborted |
— | The request was cancelled (the shopper navigated away) before the block finished. |
persisted-query-graphql |
— | A storefront GraphQL operation returned errors. |
circuit-open |
BIZZ-012 | The per-blockType circuit breaker is OPEN after repeated loader failures; the loader was skipped to shed load off the failing upstream. |
timeout-after-retries |
BIZZ-014 | Every configured retry attempt timed out; the loader escalated to TimeoutAfterRetriesError. A single-attempt timeout is BIZZ-002. |
dependency-failed |
BIZZ-005 | A block listed in dependsOn failed, blocking this block from running. |
dependency-shape |
— | A dependsOn block produced data of an unexpected shape. |
perf-budget-exceeded |
— | The block went over its render-time budget. |
Browser query errors (/_bp/q, useQuery)
GET /_bp/q/<op>?v=<json> answers { "data": ... }, or { "error": { "code": "..." } } with nothing from upstream (no messages, documents or statuses). useQuery gives you the same code as error.code, plus two codes of its own. Defined in packages/theme-runtime/src/operations.ts, packages/theme-runtime/src/server.ts and packages/theme/src/client/query.ts.
| Code | HTTP | Meaning |
|---|---|---|
NOT_FOUND |
404 | The op is not in BROWSER_QUERY_OPS (or is not a read-only, non-customer* op). Use load() for anything else. |
VARS_TOO_LARGE |
413 | v is longer than the limit (see limits). Send fewer or shorter variables. |
BAD_VARS |
400 | v is not JSON, or not a JSON object. |
UPSTREAM |
502 | The storefront GraphQL call failed, timed out or returned no data. Retry; show a fallback. |
METHOD_NOT_ALLOWED |
405 | The route answers GET only. |
INTERNAL |
500 | The route itself failed. Logged on the server. |
NETWORK |
— | (browser only) The request never got an answer: offline, aborted, blocked. |
HTTP_<status> |
— | (browser only) A non-JSON answer with that status, e.g. a proxy error page. |
Cart action errors (useCartActions)
Every cart action returns a Promise that rejects with { code, message }. Defined in packages/theme/src/client/cart-actions.ts.
| Code | Meaning |
|---|---|
NO_WINDOW |
Called during server rendering; cart actions run in the browser only. |
TIMEOUT |
The host did not answer within the cart action timeout (see limits). |
<backend code> |
Anything else is the backend's cart error code as the host passed it on (VARIANT_REQUIRED, OUT_OF_STOCK, ...; UNKNOWN when the failure carried none), with a shopper-readable message. |
Developer token HTTP statuses
What the API answers bizzpocket dev --store and whoami when they send a developer token (x-bp-dev-token). Defined in apps/backend/crates/bp-svc-stores/src/dev_tokens.rs, apps/backend/crates/bp-graphql/src/mount.rs and apps/backend/crates/bp-svc-storefront-page/src/route.rs.
| Status | Code | When | Fix |
|---|---|---|---|
| 401 | UNAUTHORIZED |
The token is malformed, unknown, revoked or expired. The answer never says which. | Ask the store owner for a new token (Settings → Developers) and check you copied all of it. |
| 403 | FORBIDDEN |
Storefront GraphQL: the document selects a root field outside the public read ops, has a mutation, or a root fragment, or names another store in storeSlug. Page endpoint: the request names a different store than the token's. |
Use --store with the token's own store, and only the ops a developer token may run (the browser-query set). |
| 429 | RATE_LIMITED |
More than 120 units a minute for this token: one per request, plus one per storefront operation a page runs (at most 32 per page). The body has retryAfter seconds. |
Wait, then retry. Reload less often (dev rebuilds only on save). |
| 422 | DEV_TOKEN_LIMIT |
Creating a token in the seller dashboard when the store already has 10 live tokens. | Revoke an unused token first. |
| 400 | INVALID_DEV_TOKEN |
Creating a token with a bad name or lifetime (see limits). | Fix the name or the number of days. |
bizzpocket whoami --store <slug> prints which store a token belongs to and when it expires, so you can tell a wrong-store 403 from a bad-token 401. See Tokens.