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 Settings → API keys; 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. Scheduled Store time is materialized only when the run handles a qualifying request.
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.
Scheduled Store time appears stopped
What you see
The modeled day does not move while a Scheduled run is active.
What it usually means
Scheduled time is materialized when the run handles its next qualifying request; no background scheduler advances an idle run.
What to do next
Check the run status, then make the next qualifying request. Manual time moves only after an explicit 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.
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, 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.
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 no-answer
What you see
Shopify Exam cannot determine an answer after a recorded request was sent.
What it usually means
The answer transcript records no-answer. It does not establish a Shopify result for that request.
What to do next
Read the shared call index beside the Practice record and keep the no-answer status visible. Do not infer a Shopify answer or whether the agent was right.
What to include for support
Include the visible source run, shared call index, timestamp and timezone, and visible error text. Never send Shopify credentials or private request/response material.
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. An HTTP 429 and a GraphQL THROTTLED error have different recovery details; a 2xx HTTP transport status alone does not prove a GraphQL call succeeded. 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. For an HTTP rate limit, wait for Retry-After only when that response actually provides it before one retry; otherwise reduce request concurrency and retry later without assuming a guaranteed window. For a GraphQL THROTTLED error, wait for the recorded errors[0].extensions.recovery.waitSeconds only when its source is meguro-derived; do not issue another read before that served wait elapses. If no recovery is supplied, reduce concurrency and retry later without inventing a wait.
What to include for support
Include the route, operation name, HTTP status, visible Retry-After value when provided, GraphQL error body when present, 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.