Skip to main content

Troubleshooting

First identify which flow failed: the runtime iframe bridge, setup/configuration, your backend's installed-extension request, a user-wide program, or OAuth account linking. Their message types and credentials differ. Start with Developer API Overview if you are unsure which flow applies.

No Response From Parent​

Open the extension from its installed entry in a Chastify lock. Opening your hosted page directly does not supply the parent bridge or a valid launch context.

Check these in order:

  1. Decode the current URL fragment and confirm it contains bridge.v: 1, bridge.nonce, and bridge.parentOrigin. Do not overwrite that fragment with your own hash router.
  2. Register the response listener before sending. Runtime requests use chastify:ext:req, v: 1, a unique string id, the current nonce, and a supported action.
  3. Send to the exact bridge.parentOrigin. The app's Allowed origins must include the hosted iframe's origin, including its scheme and port. They are the two different sides of the message exchange.
  4. Confirm the iframe finished loading. The parent registers the runtime bridge on iframe load; an immediate startup request can arrive too early. Try a user-triggered session.get after load to isolate this.
  5. Accept only a response from window.parent, the expected origin, type: 'chastify:ext:resp', version 1, and your pending request ID. Ordinary runtime responses do not echo the nonce.

The sample helper times out after 15 seconds with bridge_timeout. A timeout alone does not identify whether loading, an origin mismatch, a missing listener, or the underlying request caused the failure. An error response such as unknown_action means the parent received the request; it is a different problem from receiving nothing.

The seven supported runtime actions are session.get, state.get, metadata.get, regularActions.get, files.capabilities, files.list, and files.get. Writes, device commands, and runtime uploads require your backend. See the working examples.

For a blank iframe, also inspect its document request and browser console. Your host must serve the page successfully and permit Chastify to embed it; a browser embedding error cannot be repaired by changing the bridge nonce.

Backend Credentials and Role Errors​

Installed-extension requests use both an app-scoped Developer key and the current x-chastify-main-token. The URL uses the installed extension's sessionId, not its app ID or lock ID.

ErrorWhat to check
app_scoped_key_requiredA user-wide key belongs with /api/apps/v1/*, not installed-extension session routes.
main_token_requiredForward the current launch token to your backend and include its header. The nonce is not this token.
invalid_main_token, revoked_main_token, expired_main_tokenObtain a new launch context by reopening the extension and update the backend's launch context.
session_mismatch, lock_mismatch, extension_mismatchThe key, launch token, route session, and installed app must refer to the same context.
grant_role_mismatchThe launch user's wearer/keyholder role changed. Reopen from the account that currently has the required role.
server_credentials_requiredThe mutation needs backend authentication; sending it through the browser bridge will not supply that.
insufficient_scopeCheck both the key's permissions and the installed extension's effective scopes.
forbidden or an action-specific role/trust errorThe current caller or lock settings do not authorize that operation. A backend key does not elevate a wearer to keyholder.

Launch tokens currently expire after ten hours. Issuing another token for the same user and installed extension revokes earlier grants, so opening a second tab can invalidate the first tab's backend token. Do not poll the /auth endpoint to refresh ordinary session data.

Keep Developer keys on your server. For other credential types, use External API & Programs or OAuth Account Linking.

403 extension_not_enabled​

The installed extension is disabled for this lock. Open its configuration and enable/save it through the authorized Chastify UI, then reopen it. Availability in the extension catalogue does not mean it is enabled on this lock.

A 404 extension_not_found can instead mean the underlying app is unavailable or inactive. For an unreleased app, check developer/tester access using Extension Release & Beta Testing.

409 lock_ended​

The lock session is no longer eligible for extension operations. Stop its background reads and writes and return to Chastify to check the session. Repeating the request or changing the token does not reactivate an ended session.

Do not substitute a different active lock automatically when an operation fails. Start a new launch deliberately and keep its identifiers separate from the previous session.

429 Rate Limit​

The installed-extension defaults are 300 reads, 120 writes, 10 uploads, 30 actions, and 30 token requests per minute. App overrides and other route families can differ. Endpoints share their applicable bucket; setup requests by one user can also share capacity across apps.

For direct HTTP requests, inspect Retry-After or JSON retryAfter and wait before a bounded retry. X-RateLimit-Reset is an ISO timestamp. See Rate Limits for counting rules and endpoint mapping.

The runtime bridge reports error.code: 'rate_limit_exceeded' but currently does not forward HTTP status or the retry delay. Pause reads for a minute and offer a retry. Checking only error.status === 429 in the iframe will miss this response.

Avoid duplicate effects

An explicit rate-limit rejection and a lost response are different outcomes. A timeout or server error after submitting an action may leave its result uncertain. Check state, history, or delivery status before repeating time changes, tasks, progress, or device commands.

Device Command Fails​

For an installed extension, read session.get and its deviceControl.supportedCommands before offering a control. Recheck when the device or lock settings change. The user-wide session response has a different shape; do not expect the iframe capability object there.

Send the command through your backend with the required credentials. bridge.request('device.command', ...) is unsupported.

Check the returned error against:

  • The wearer's configured device, its capabilities, and available delivery route.
  • Current wearer/keyholder permissions, consent, and lock/device policy.
  • The command's parameters and model-specific support, especially timed random/berserk modes.
  • Queue, connection, or acknowledgement status.

An accepted request may be queued; active flags are not a physical delivery receipt. A stop result is also not proof that every device has stopped or that all outstanding mandatory deliveries were cancelled. Follow Shock Delivery & Queues and the device command examples.

Setup Page Not Saving Config​

Setup uses a separate protocol from the runtime bridge. Use the setup launch's nonce and parent origin, and validate message source, origin, and version.

  1. Register listeners, then send chastify:ext:setup:ready with v: 1 and the current nonce.
  2. Handle chastify:ext:setup:init, which contains existing config and context. Initialize your form without dropping fields it does not own.
  3. Send chastify:ext:setup:config with the current full configuration when it changes.
  4. Answer chastify:ext:setup:get_config promptly with another chastify:ext:setup:config. The parent waits about 1.5 seconds before using its last draft, so do not start an upload or other slow work at this point.
  5. Save through the parent Chastify UI. Sending a configuration message updates its draft; it does not persist the lock or template by itself.

Inspect validation or eligibility errors shown after Save. Keep the draft available so the user can correct it. A setup upload response alone does not mean its reference was claimed in saved configuration.

See Setup protocol and the sample apps/extension/src/pages/SetupPage.tsx.

Uploaded Image Is Missing​

Store a stable file ID, then request a fresh signed URL for display. Signed URLs normally expire after ten minutes. A browser blob: URL only refers to the local preview, and an extension-file:ID reference is not itself an image URL.

For setup images, save the structured chastify_storage reference and actual configuration before the draft expires after 24 hours. Check the setup/runtime ownership limitations in Extension File Storage: a successfully claimed setup file is not automatically readable through every runtime file route.

files.capabilities.enabled reports whether uploads are available. It does not itself forbid reading existing files. For file_not_found, check the app/user/session/lock context rather than removing ownership checks or substituting another file ID.

Webhook Is Missing or Repeated​

Check the app's webhook setting, saved endpoint, receiver response, and current token configuration. A successful test request checks that path at that moment; it does not prove every future event will arrive.

Events can be retried, delayed, or dropped after delivery failure. The current payload ID is regenerated on retries, so it is not a stable deduplication key for one source event. See Webhooks for supported events and delivery limitations before triggering side effects from a callback.

What to Include in a Developer Report​

Include the affected flow, endpoint/action, approximate time, reproduction steps, HTTP status or bridge error code, and a sanitized response. State whether the failure happens in setup, after installation, or only after reopening/changing the session.

Remove Developer keys, launch/access tokens, webhook authentication values, signed image URLs, private configuration, and personal content. Never share a full iframe launch URL. Use Contacting Support for the appropriate channel.