Troubleshooting

Find the failing layer before retrying the action.

Most product problems belong to one of a few boundaries: Shopify authorization, storefront access, staging state, session lifecycle, QA, available capacity or deployment authority. Start with the visible evidence.

Direct answer

Troubleshoot the affected layer in order—connection, staging, session, QA, billing and deployment—without exposing credentials or bypassing controls.

Store connection

The store does not connect or the active theme is missing.

Confirm the canonical myshopify.com domain, Shopify app-install permission and that the installation was completed from the intended merchant account. Reconnect through OAuth rather than pasting credentials.

Preview

The staging preview is blank, protected or returns 404.

Confirm the storefront password, open the staging URL directly and use Repair staging when required theme assets are missing. A live storefront that works does not prove the staging copy is complete.

Session

A session looks active or no specific lifecycle state appears.

Open the session to inspect its latest conversation and changeset. Older sessions outside the recent actionable queue may display Active session rather than an inferred build or review state.

QA

The implementation failed QA or does not match the preview expectation.

Request correction and describe the observed behavior. Do not approve solely because some checks passed, and do not use force deployment as the normal path around failed QA.

Automations and capacity

A background run failed or new work cannot start.

Check the Automation status, store connection and Billing capacity. An insufficient balance prevents the product from reserving enough Engineering Runs to begin qualifying work safely.

Support request

Send evidence without sending secrets.

Include the shop domain, session or run reference, visible status, expected behavior, observed behavior, time and safe reproduction steps. Never send passwords, Shopify tokens, JWTs, API keys or customer data.

Questions

Direct answers before installation

Why does the page appear to refresh while loading?

A layout should reserve its final structure while authenticated data loads. Report persistent remounting with the exact route and browser after ruling out an expired session.

Why can I not close the session without implementation?

The session may already be completed or contain published work. Those states cannot be relabeled as abandoned.

Why can I not approve or deploy?

Your team role may not have authority, QA may have failed or the changeset may not be in a valid transition state.

What should I include in a support request?

Store domain, record reference, status, timestamp, expected result, observed result and non-sensitive screenshots or reproduction steps.

Should I retry repeatedly?

No. Repeated attempts can obscure the original state. Identify the failing layer and retry only after the underlying issue is understood.

Next step

Connect the store. Start with evidence.

Run the connected-store audit, review prioritized findings and decide which bounded engineering job should move to staging first.