Skip to main content
Live with caveats. This area is real and usable, but the docs intentionally call out operational or UX limits that still matter.

​
Goal

Diagnose Shopify hosting failures using persisted evidence while preserving tenant and environment isolation.

​
Prerequisites

  • Project access
  • The failed operation or release ID
  • Application logs for app-owned OAuth, session, or webhook failures

​
Workflow

1
Identify whether the failure is connection, target verification, backend deployment, Shopify release, storefront promotion, or ingress observation.
2
Read the durable operation/release status, step, stable error code, redacted message, and attempt count.
3
Compare target has_* flags and verification timestamps with the current committed branch configuration.
4
Resolve the specific gate; do not bypass isolation by copying production credentials into development.
5
Retry only after the underlying state changed, then re-check launch checks and runtime health.

​
Credential guarantees and limits

  • Client secrets, automation tokens, private Storefront tokens, Customer Account secrets, and generated session secrets are encrypted at rest with the platform encryption key.
  • Public Storefront tokens are stored as non-returning credential data but are not encrypted because they are designed for public clients. They are still omitted from API responses and logs.
  • Secret fields reject values over 8 KiB and CR, LF, or NUL bytes. Identifier/scopes fields are limited to 512 characters; URLs are clean HTTPS origins.
  • Credentials are decrypted only when building the selected runtime environment or executing a constrained verification/release step.
  • StackShift does not store merchant OAuth access tokens, Shopify session tokens, webhook bodies, or webhook HMAC headers for this feature.

​
Launch-check interpretation

  • A ready connection requires ready development and production credential targets. Storefront preview readiness is not required for connection readiness.
  • App launch additionally requires reachable callback/webhook routes, a healthy production backend, a healthy development backend and Shopify release, and supported observed webhook API versions.
  • Shop Pay checks appear only when Shop Pay is requested and require production credentials, TLS, checkout confirmation, and component evidence.
  • Pending means evidence is not yet available; it must not be treated as passing. Invalid means a concrete check failed and includes a target error message.

​
Diagnosis by error code

  • SHOPIFY_INVALID_CREDENTIALS: confirm token type, target ownership, expiry/rotation, store domain, and whether credentials changed after verification was queued.
  • SHOPIFY_CONFIG_MISMATCH: compare committed TOML at the target branch with saved config path/name, client ID, and webhook API version.
  • SHOPIFY_INCOMPATIBLE_DATABASE: confirm the generated/bound database is project-owned PostgreSQL, running, and exposes a connection string.
  • SHOPIFY_UNSUPPORTED_HYDROGEN_RUNTIME: add a supported Node adapter and start command; Oxygen-only runtime is not deployable here.
  • SHOPIFY_FAILED_HEALTH_GATE: inspect route status, runtime/deployment health, preview activity/expiry/digest, TLS, or active-release conflicts based on the operation.
  • SHOPIFY_RATE_LIMITED: keep the operation durable and allow its bounded retry schedule; do not fan out manual retries.

​
Escalate immediately

  • A release is degraded, indicating backend or Shopify compensation could not restore a consistent known state.
  • A critical WEBHOOK_REPEATED_5XX alert remains open after application recovery.
  • A secret appears in a persisted log or API response; revoke/rotate it in Shopify first, then preserve the incident evidence.
  • Production and development point to the same app identity, URL, or database despite validation expectations.

​
Expected result

The failed layer is identified from durable evidence and restored without exposing credentials or weakening production gates.

​
Common failures

  • Reading a redacted generic error without opening the associated durable operation/release
  • Retrying before rotating an expired token or fixing committed configuration
  • Treating observed webhooks as proof of HMAC verification
  • Using the platform server environment for tenant credentials
  • Treating a degraded compensated release as healthy

Shopify hosting overview

What StackShift hosts, what remains in Shopify, who supplies credentials, and how app and storefront hosting differ.

Shopify hosting API reference

Authenticated project endpoints, strict request contracts, asynchronous operations, status values, and stable Shopify error codes.

Shopify webhooks and observability

Application-owned HMAC verification, metadata-only ingress observations, duplicate accounting, retention, alerts, and launch checks.