Testing & Debugging

Your app runs inside someone else's site, so SitePack is strict about what it accepts, and it fails quietly on the storefront rather than breaking a merchant's page. This page tells you where each check happens and where to look when something does not show up.

The test loop

Install the app once on a site you manage (see Try the app on your own site).
Change your files and run sitepack app:publish.
Reload the storefront and the app's settings page in the admin.

There is no local preview for apps: a publish is the way to see a change. Every publish creates a new version, so do not be shy with it while the app is private.

Publishing a live app

A publish goes straight to every site that has your app installed, without a review. Once your app is in the Marketplace, test on your own site first and keep the settings schema backwards compatible.

What is checked, and where

Where	What	What you see
`sitepack app:publish`	Every `.json` file must be valid JSON; only `app.json`, `templates/`, `assets/` and `translations/` are uploaded	The CLI stops and names the file
The upload	Every file is scanned for malware	The publish is refused
The Review checklist in the Partner Portal	Icon, listing, `app.json` fields, every template and script in the manifest exists, image defaults, unused or ignored settings	A list of passed, warned and blocking checks on your app page
The storefront, on every render	The sandbox: only allowed tags, filters and functions; no `raw`, `include` or `extends`	The block is left out; see below
The settings form, on save	Values are typed by your schema, unknown keys are dropped, image settings must be a media library image or your default	The form names the field
The API, on every call	Token valid, installation active, scope granted	`401`, `403` or `429` with an `error.code`

My block does not show up

Work through these in order:

Is the app installed on this site? It must be listed under Apps in the site's admin, as an active app. Blocks and scripts only render on sites where the app is installed.
Did the template fail? Open the page source (not the element inspector) and search for Error rendering app template. When a template breaks the sandbox or throws an error, SitePack leaves your block out and puts the reason in an HTML comment at that spot:
```

```
Does your own condition hide it? A good template renders nothing until the required settings are filled in, like the WhatsApp button without a phone number. Fill in the settings page and save.
Is the block spot on this page? head, body_start and body_end are on every page. The others only exist on their page: product_form_after on a product page, account_login_before on the login page. See Where a block can hook.
Is the storefront still showing the old version? The storefront keeps a short-lived copy of each site's setup. Saving your app's settings page on that site refreshes it straight away.

My script does not run

Scripts load at the end of <body> as classic deferred scripts, not modules. import and export fail; wrap your code in an IIFE.
Check the browser console. The script URL is https://cdn-app.sitepack.eu/<uuid>/<version>/assets/js/<file>; a 404 there means the file is not under assets/js/ or not listed in "scripts" in app.json.
Scripts from other domains are blocked by the Content Security Policy. Ship everything inside your app.
Tags that need consent should wait for it: check window.SitePackTracking.consent and listen for sitepack:cookies:consent. See Storefront Blocks & Events.

My settings form looks wrong

A label shows a key like admin.settings.phone_number.title. That key is missing from translations/en.json. English is the fallback for every language, so add it there first.
A field I added does not appear. The form reads the published app.json. Run sitepack app:publish and reload the settings page.
translatable does nothing. Only top-level free-text string settings can be translatable; the Review checklist warns about the others. See Translations.

My API calls fail

Every error response carries a machine-readable error.code:

{ "status": "error", "error": { "code": "scope_required", "message": "...", "scope": "orders:read" } }

Status	Usual cause
`401`	The access token expired (refresh it), or the merchant removed your app
`403`	The scope is not granted, or the installation or its paid subscription is no longer active
`404`	The uuid does not exist on this site. A token is bound to one site
`422`	Validation failed; `error.field` names the field
`429`	Rate limited; wait for `Retry-After` seconds

GET /api/public/v1/me shows which site the token belongs to and which scopes are in force right now. Start there when you are unsure.

My webhooks do not arrive

Check that the topic and the https:// address are in the published app.json. Your app page in the Partner Portal lists them under App Webhooks.
Click Test next to a topic to send a signed test message with "test_mode": true.
A signature mismatch is almost always a re-serialized body. Verify over the raw bytes you received. See Webhooks.
Anything other than a 2xx is retried once, about 5 seconds later. A handler that is down longer misses the event, so also sync from the list endpoints now and then. See Delivery and retries.

Still stuck?

Check the FAQ. If that does not help, contact SitePack support with your app uuid, the site and what you expected to happen.

The test loop​

What is checked, and where​

My block does not show up​

My script does not run​

My settings form looks wrong​

My API calls fail​

My webhooks do not arrive​

Still stuck?​