BizzPocket

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.