Retry transient server errors for theme API reads

[lizkenyon]

WHY are these changes introduced?

Theme commands currently fail on the first Admin API response containing INTERNAL_SERVER_ERROR, even when the response comes from a brief server-side interruption and the request is safe to repeat.

Because theme requests preserve raw GraphQL errors for theme-specific handling, exhausted failures are also reported as unexpected CLI crashes instead of giving the user a clear recovery step.

WHAT is this pull request doing?

Adds an opt-in retry policy for transient GraphQL and gateway errors. The policy only applies to query-only documents, uses three retries with exponential backoff, and is enabled for theme API requests. Mutations are never retried.

If the request still fails, theme commands return a handled error with a request ID when available instead of exposing the raw GraphQL response.

How to manually test your changes?

No live-store failure is required. With a local GraphQL fixture or proxy:

1. Return an HTTP 200 INTERNAL_SERVER_ERROR once, then a successful response for a theme read, and confirm the command recovers.
2. Return the error for every attempt and confirm the final message asks the user to retry and includes the request ID without the raw response.
3. Return the same error for a mutation and confirm it is sent only once.

Checklist

• I've considered possible cross-platform impacts (Mac, Linux, Windows)
• I've considered possible documentation changes
• I've considered analytics changes to measure impact
• The change is user-facing — I've identified the correct bump type (patch for bug fixes · minor for new features · major for breaking changes) and added a changeset with pnpm changeset add

[Copilot]

🟡 Changes recommended

Two theme query paths still bypass the new retry policy and transient-error handling.

1 open finding

• Theme reads omit network opt-in and transient retry handling · New

What changed in this PR

Adds safe retries and clearer errors for transient theme Admin API read failures.

Changes:

• Retries query-only transient GraphQL/gateway failures with exponential backoff.
• Converts exhausted theme failures into handled errors with request IDs.
• Adds coverage and a patch changeset.

File	Description
packages/​cli-kit/​src/​public/​node/​themes/​api.ts	Enables theme retries and friendly errors.
packages/​cli-kit/​src/​public/​node/​themes/​api.test.ts	Tests theme error handling.
packages/​cli-kit/​src/​public/​node/​api/​graphql.ts	Restricts retries to query-only documents.
packages/​cli-kit/​src/​public/​node/​api/​graphql.test.ts	Tests query and mutation behavior.
packages/​cli-kit/​src/​private/​node/​api.ts	Implements transient-error retries and backoff.
packages/​cli-kit/​src/​private/​node/​api.test.ts	Tests retry limits and classification.
packages/​cli-kit/​src/​private/​node/​analytics/​graphql-error-codes.ts	Recognizes transient GraphQL codes.
packages/​cli-kit/​src/​private/​node/​analytics/​graphql-error-codes.test.ts	Tests transient-code detection.
.changeset/​theme-retry-transient-server-errors.md	Documents the user-facing patch.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[github-actions]

Differences in type declarations

We detected differences in the type declarations generated by Typescript for this branch compared to the baseline ('main' branch). Please, review them to ensure they are backward-compatible. Here are some important things to keep in mind:

• Some seemingly private modules might be re-exported through public modules.
• If the branch is behind main you might see odd diffs, rebase main into this branch.

New type declarations

We found no new type declarations in this PR

Existing type declarations

packages/cli-kit/dist/private/node/api.d.ts

@@ -1,14 +1,24 @@
 import { Headers } from 'form-data';
+import { ClientError } from 'graphql-request';
 export type API = 'admin' | 'storefront-renderer' | 'partners' | 'business-platform' | 'app-management';
 export declare const allAPIs: API[];
-export type NetworkRetryBehaviour = {
+interface CommonRetryBehaviour {
+    recordCommandRetries?: boolean;
+    /**
+     * Retry, with backoff, requests that fail with a transient server-side error: a GraphQL
+     * `INTERNAL_SERVER_ERROR` (usually on an HTTP 200) or an HTTP 502/503/504.
+     *
+     * Only enable this for requests that are safe to repeat. GraphQL requests only honour it for
+     * queries; mutations are never retried on these errors.
+     */
+    retryTransientServerErrors?: boolean;
+}
+export type NetworkRetryBehaviour = ({
     useNetworkLevelRetry: true;
     maxRetryTimeMs: number;
-    recordCommandRetries?: boolean;
-} | {
+} & CommonRetryBehaviour) | ({
     useNetworkLevelRetry: false;
-    recordCommandRetries?: boolean;
-};
+} & CommonRetryBehaviour);
 type RequestOptions<T> = {
     request: () => Promise<T>;
     url: string;
@@ -52,6 +62,15 @@ export declare function isNetworkError(error: unknown): boolean;
  * @returns A boolean indicating if the request was aborted.
  */
 export declare function isAbortedFetchError(error: unknown): boolean;
+/**
+ * Checks whether an error is a transient server-side failure that is likely to succeed if retried:
+ * a GraphQL `INTERNAL_SERVER_ERROR` (Shopify APIs usually return it on an HTTP 200), or an HTTP
+ * 502, 503 or 504.
+ *
+ * @param error - The error to check.
+ * @returns Whether the error is a transient server-side failure.
+ */
+export declare function isTransientServerError(error: unknown): error is ClientError;
 export declare function simpleRequestWithDebugLog<T extends {
     headers: Headers;
     status: number;

packages/cli-kit/dist/private/node/analytics/graphql-error-codes.d.ts

@@ -36,4 +36,11 @@ export declare function isPermissionCode(code: string | undefined): boolean;
  * @param errors - The `errors` value from a GraphQL response.
  * @returns True when a rate-limit code is present in any error.
  */
-export declare function hasRateLimitCode(errors: unknown): boolean;
\ No newline at end of file
+export declare function hasRateLimitCode(errors: unknown): boolean;
+/**
+ * Whether any GraphQL error carries a transient server-side failure code.
+ *
+ * @param errors - The `errors` value from a GraphQL response.
+ * @returns True when a transient server code is present in any error.
+ */
+export declare function hasTransientServerCode(errors: unknown): boolean;
\ No newline at end of file

packages/cli-kit/dist/public/node/upgrade/types.d.ts

@@ -51,11 +51,11 @@ export declare const upgradeJsonOutputSchema: import("../json-output-schema.js")
     scope: zod.ZodEnum<["global", "local"]>;
 }, "strict", zod.ZodTypeAny, {
     status: "skipped";
-    scope: "local" | "global";
     reason: "development" | "local-autoupgrade" | "dependency-not-found";
+    scope: "local" | "global";
 }, {
     status: "skipped";
-    scope: "local" | "global";
     reason: "development" | "local-autoupgrade" | "dependency-not-found";
+    scope: "local" | "global";
 }>]>>;
 export type UpgradeResult = InferJsonOutputSchema<typeof upgradeJsonOutputSchema>;
\ No newline at end of file

[graygilmore]

@lizkenyon will this conflict with #8897?

[lizkenyon]

@lizkenyon will this conflict with #8897?

Feel free to merge yours first andI can adjust! @graygilmore