Skip to content
OpenShopOpenShopOpenShop

Troubleshooting

Find your symptom below. Run CLI commands from the app root with DATABASE_URL exported for the intended environment. Start by checking migration status and whether the HTTP process responds:

Terminal window
pnpm exec openshop migrate status
curl -i http://localhost:3000/health

The health endpoint does not check the database or worker. For a complete verification, run a smoke flow.

The app does not install

Section titled “The app does not install”
  1. Confirm the shop ends in .myshopify.com.
  2. Verify SHOPIFY_API_KEY, SHOPIFY_API_SECRET, and HOST.
  3. In multi-app mode, include app=<handle> and confirm that handle exists.
  4. Deploy the matching Shopify TOML and ensure its application URL points to the same HOST.
  5. Retry from /auth?shop=<shop>&app=<handle>.

An Invalid HMAC response means the request was not signed with the selected app secret. A state error means the OAuth callback is stale or belongs to a different installation attempt.

The embedded UI returns 401

Section titled “The embedded UI returns 401”

Open the app from Shopify admin instead of navigating directly to its host. The production UI requires a valid shop launch and an installed shop. For API calls, send a fresh App Bridge session token as a bearer token.

Runs stay pending

Section titled “Runs stay pending”

openshop start queues runs but does not execute them.

Terminal window
pnpm exec openshop worker --concurrency=5

Check that web and worker use the same DATABASE_URL and built config. If a run is scheduled in the future, inspect availableAt. If the worker repeatedly loses work, compare leaseDurationMs with the longest non-checkpointed work.

A run retries or fails unexpectedly

Section titled “A run retries or fails unexpectedly”
  • Search the run logs and inspect the failed step.
  • Ensure step output is JSON serializable.
  • Make provider writes idempotent because a failed step can run again.
  • Pass ctx.signal to abortable calls; JavaScript cannot forcibly stop arbitrary user code.
  • Compare flow timeouts with retry delays. A retry scheduled after the flow deadline is not attempted.

Database tables are missing

Section titled “Database tables are missing”

Apply the committed migration before starting either process:

Terminal window
pnpm exec openshop migrate
pnpm exec openshop migrate status

Generate migrations only during development or CI. Production schema generation is intentionally blocked.

GraphQL types are stale

Section titled “GraphQL types are stale”
Terminal window
pnpm run codegen
pnpm run lint

Confirm the operation is inside a supported #graphql literal and that the configured Shopify scopes allow the operation.

Proxy or extension calls return 401

Section titled “Proxy or extension calls return 401”

For /proxy/*, configure a Shopify App Proxy or send a Customer Account session JWT. For /ext/*, send a Customer Account JWT; App Proxy query HMAC alone is not accepted. Verify the token audience matches the selected Shopify app.

Provider secrets cannot be read back

Section titled “Provider secrets cannot be read back”

Password fields are intentionally write-only. An empty password submitted from the admin keeps the current value. To replace it, submit a new value. If the ENCRYPTION_KEY changed, restore the original key; existing ciphertext cannot be decrypted with a replacement.

The test command cannot find a bootstrap

Section titled “The test command cannot find a bootstrap”

The minimal template defines the test script but does not create a test suite. Follow Test an app to add tests/bootstrap.ts and a dedicated test database.

Still stuck?

Section titled “Still stuck?”

Collect the OpenShop version, failing command or URL, run ID, and relevant web or worker error message. Remove credentials and customer data, then open an issue with a minimal reproduction.