# Troubleshooting and recovery Concrete recovery steps for authentication, runs, Store time, receipts, limits, networking, service failures, deletion, and billing. ## Scope and proof boundaries Start with the exact visible state, take the bounded next action, and stop before an ambiguous retry. Every entry below keeps support details customer-safe. Never send access tokens, API keys, credentials, authorization headers, private request payloads, secrets, or customer PII/data. ## 401 or 403 authentication failure ### What you see A request returns `401`, `403`, `unauthorized`, `forbidden`, or “sign in or present an API key.” ### What it usually means The credential is missing, invalid, revoked, expired, or not allowed to reach that workspace or store. A workspace API key and a per-store Admin token are not interchangeable. ### What to do next Sign in again for dashboard requests. For an external control client, create or select a valid workspace API key in Connection settings; for an agent’s Admin request, recopy that store’s Admin URL and token. Retry one read before starting or changing a run. ### What to include for support Include the route, whether the request came from the dashboard, a control client, or an Admin client, the timestamp and timezone, and the exact visible error text. Never include the credential or authorization header. ## Wrong credential type: workspace key versus per-store Admin token ### What you see A credential works in one Meguro surface but is rejected by another, or an Admin client never records its first read. ### What it usually means Workspace control keys beginning `meg_sk_…` authenticate external control clients to one workspace. Per-store Admin tokens beginning `meg_pw_…` authenticate an agent only to one practice store. ### What to do next Use the workspace key only with the public control API or local control tooling. Use the per-store token with that store’s Admin GraphQL URL and `X-Shopify-Access-Token`, then confirm one read. ### What to include for support Include the route, client type, store ID when visible, timestamp and timezone, and exact visible error. State only which credential type you used; never send its value. ## Unsupported GraphQL field or mutation ### What you see The response contains GraphQL errors or `userErrors` naming an unsupported field, mutation, argument, or shape. ### What it usually means The request is outside the declared Shopify-shaped practice surface. Unsupported calls fail loudly instead of returning fake success. ### What to do next Open Supported Admin GraphQL surface, compare the exact operation family, and use a supported representative action when one preserves the job. Otherwise record the gap and do not count the call as compatible. ### What to include for support Include the operation name, requested API version when visible, route, store/run ID, timestamp and timezone, and exact public error text. Do not send variables, private payloads, or customer data. ## Agent makes reads but no writes ### What you see Calls are recorded, but the receipt shows no accepted representative write, “no writes,” or report-only evidence. ### What it usually means The client connected, but it did not issue or complete the write that represents the agent job. Reads may occur before a run; writes require an active run. ### What to do next Start a run, name one supported bounded write, run the agent again, and inspect whether the call was accepted, rejected, or unsupported. A zero-write or report-only run does not establish impact. ### What to include for support Include the visible store and run IDs, route, timestamp and timezone, intended operation name, exact visible status, and whether it persists after reload. Do not send the request payload. ## Run waiting for the agent’s first call ### What you see The run says “Waiting for your agent’s first call” and no call appears. ### What it usually means The observation window is armed, but the agent has not reached this store’s Admin URL with its per-store token. Automatic Store time begins only after the first agent call. ### What to do next Verify the agent process is running, recopy the current store Admin URL and per-store token, and send one authenticated read. Do not start another run until this run records or rejects that call. ### What to include for support Include the route, store/run ID, timestamp and timezone, agent client name, exact visible waiting text, and whether reload changes it. Never send the Admin token. ## Automatic or code-controlled Store time appears stopped ### What you see The modeled day does not move while an automatic or code-controlled run is active. ### What it usually means Automatic time may still be waiting for the first agent call. Code-controlled time moves only when the runner sends an allowed advance with the server-owned practiceRun.advanceCursor. ### What to do next Check the run status and current clock mode. For automatic time, confirm the first authenticated call. For code-controlled time, fetch fresh status and copy its practiceRun.advanceCursor object unchanged into advance. ### What to include for support Include the run ID, clock mode, displayed Store day, route, timestamp and timezone, exact visible status, and whether it persists after reload. Do not send runner authorization. ## Concurrent Store-clock change ### What you see An advance is rejected with “scenario clock changed concurrently” or another message that the Store clock changed concurrently. ### What it usually means Another accepted call or advance changed the run coordinate after the client last read it. The stale expected day or call sequence cannot be applied. ### What to do next Fetch the current run status, replace the stale expected day and expected call sequence with the returned values, create a fresh one-time authorization when required, and retry the one intended advance once. ### What to include for support Include the run ID, displayed clock mode and current coordinate, route, timestamp and timezone, exact visible error, and whether a fresh status read changed the coordinate. Never send the authorization value. ## Run or receipt unavailable after completion or reload ### What you see A completed run or receipt is missing, unavailable, or reported as expired after reload. ### What it usually means The simulation run may not have ended durably, the selected workspace may differ, or the receipt may be outside the active plan’s availability window. An ID or hash alone cannot recreate a result. ### What to do next Reload once, confirm the selected workspace and store, reopen the simulation run from its history, and use a previously retained artifact if the receipt availability window has ended. Do not manufacture a replacement result. ### What to include for support Include the visible run or receipt ID, workspace name without customer data, route, completion time and timezone, exact visible status, and whether it persists after reload. ## Missing agent identity or requested API version ### What you see The receipt says agent identity is missing or “Requested API version was not captured for these calls.” ### What it usually means The run recorded behavior, but it lacks a declared identity or version coordinate needed for the claim you want to make. The missing field cannot be inferred later. ### What to do next Configure the client to declare its agent/build identity and intended Shopify Admin API version, then create a new run and confirm both fields appear before relying on the new receipt for version coverage. ### What to include for support Include the receipt/run ID, route, timestamp and timezone, exact visible missing-field text, client name, and whether a fresh run reproduces it. Do not send source, payloads, or credentials. ## Shopify Exam eligibility or blocker ### What you see Shopify Exam is unavailable or names an eligibility, setup, replay, comparison, historical materialization, or cleanup blocker. ### What it usually means The captured run does not currently satisfy the explicit Exam contract for the selected development-store target and exercised operations. ### What to do next Open the run, follow its named blocker, and correct only that eligibility or setup condition before creating a new Exam run. Ordinary practice evidence does not become live-Shopify proof while the blocker remains. ### What to include for support Include the practice-run and Exam-run IDs, blocker code and visible message, requested API version, timestamp and timezone, and whether reload changes the blocker. Never send Shopify credentials or private receipt bytes. ## Expired one-time or runner authorization ### What you see The product says “Authorization expired,” “Local runner authorization has expired,” or reports an unavailable one-time authorization. ### What it usually means The short-lived, command-bound authorization expired, was revoked, was already used, or no longer matches the run’s current Store-time coordinate. ### What to do next Fetch the current run state, create a new authorization for the exact current command and coordinate, replace the expired value in the runner, and retry. Never reuse an expired one-time authorization. ### What to include for support Include the run ID, command name, current displayed coordinate, route, timestamp and timezone, exact visible error, and whether a newly created authorization succeeds. Never send either authorization value. ## Simulation canvas, simulation-run, receipt-retention, active-store, or workspace limit ### What you see Meguro stops an action and names a simulation-canvas, simulation-run, receipt availability, active-store, or active-workspace limit. ### What it usually means The current enforced plan contract does not allow that action or capacity. Existing readable stores and evidence are not upgraded or invalidated by the limit message. ### What to do next Open Usage and Plans and billing to identify the exact limit. Finish or cancel work before deleting an active store, archive an unused workspace to release its slot, retain receipts within their availability window, or choose a plan whose enforced capacity fits the work. ### What to include for support Include the account email, exact limit name and visible counts, route, timestamp and timezone, exact visible message, and whether reload changes it. Do not include billing credentials or customer data. ## Public receipt or hash integrity versus result verification ### What you see A public receipt hash matches, or a reviewer asks whether a matching digest proves the result. ### What it usually means The digest verifies the artifact bytes and detects alteration. It does not verify that the evidence supports the result, expand the exercised scope, or turn modeled evidence into live proof. ### What to do next Verify the digest, then separately review the receipt’s goal outcome, recorded calls, evidence classification, proof boundaries, target, and exercised operation scope. ### What to include for support Include only the public receipt ID or URL, digest, issuance time and timezone, route, and the exact visible integrity result. Do not send private receipt content or customer data. ## HTTP 429 or throttling when applicable ### What you see A request returns `429` or a visible throttling message. ### What it usually means The applicable surface declined the request at that moment. Practice rate-limit evidence is bounded to the exercised mode and is not a claim of exact Shopify rate-limit parity. ### What to do next Stop parallel retries. If the response provides `Retry-After`, wait for that visible duration before one retry; otherwise reduce request concurrency, fetch fresh state, and retry later without assuming a guaranteed window. ### What to include for support Include the route, operation name, status code, visible `Retry-After` value when provided, timestamp and timezone, run ID, exact visible error, and whether one later retry changed it. ## CORS or client networking failure ### What you see A browser or client reports CORS, a blocked preflight, failed fetch, DNS/TLS failure, or no HTTP response. ### What it usually means The client may be using the wrong public origin or route, a browser-only request may not be allowed there, or the network failed before Meguro returned a product response. ### What to do next Confirm the current public URL and route, reload once, retry from the intended client, and use the documented server-side or MCP path when a browser origin is not supported. Do not disable browser security. ### What to include for support Include the route and public origin, client/browser name and version, timestamp and timezone, exact visible network text, whether any status code appeared, and whether reload reproduces it. Do not send headers or payloads. ## HTTP 500 or service failure ### What you see A request returns `500`, “internal server error,” or a visible service-failure message. ### What it usually means Meguro could not complete that request. The error does not establish whether a write occurred, so repeating a mutation immediately could create ambiguous evidence. ### What to do next Stop the workflow, reload once, inspect the visible run or store state, and retry a read-only status request. Do not repeat a write unless the current state shows it is safe; contact support if the failure persists. ### What to include for support Include the account email, route, visible store/run/receipt ID, timestamp and timezone, exact visible error text, and whether it persists after reload. Never send request payloads, authorization headers, credentials, secrets, or customer data. ## Account and practice-store deletion ### What you see Delete account or Delete practice store is unavailable, blocked, expired, or does not complete after confirmation. ### What it usually means An active run can protect a store from deletion; a store deletion preview can become stale or single-use; permanent account deletion is owner-only, requires recent sign-in, and may resume in bounded steps. ### What to do next For a practice store, finish or cancel its active run, request a fresh deletion preview, and confirm again. For an account, sign in again, open Account settings as the owner, type the required confirmation, and resume only from the displayed deletion state. ### What to include for support Include the account email, route, visible store ID or deletion phase, timestamp and timezone, exact visible error, and whether it persists after reload. Never send confirmation tokens, credentials, private payloads, or customer data. ## Billing, checkout, or subscription support ### What you see Checkout is canceled or delayed, a plan change is not reflected, payment is past due, or Manage billing is unavailable. ### What it usually means The account may still be waiting for a signed payment update, the action may require the account owner, or the current subscription state may keep Free limits in effect. ### What to do next Open Plans and billing as the account owner. After a delayed return, use Check again once and do not submit Checkout again while confirmation is pending. Use Manage billing for the current subscription or contact support if the signed update remains missing. ### What to include for support Include the account email, route, selected plan and interval, timestamp and timezone, exact visible billing text, and whether it persists after reload. Never send card details, checkout URLs, credentials, or payment secrets.