fileUpdate returns FILE_LOCKED even though MediaImage is READY

GraphQL Admin API Troubleshooting
1

We encountered a MediaImage that consistently returns:

FILE_LOCKED: File id 39592597422301 has a pending operation.

Original MediaImage: gid://shopify/MediaImage/39592597422301

Querying the file shows:

fileStatus: READY
fileErrors: []

However, fileUpdate(referencesToAdd) still fails with FILE_LOCKED.

Target Product: gid://shopify/Product/9654702047453

One confirmed failed request:

X-Request-ID: e286463b-eb9a-43f9-87b0-819053fe00cc-1788596949

The lock persisted for hours even though the public file status remained READY.

To test whether this was related to the image content or product, we recreated the exact same source image as a new File.

fileCreate

UTC: 2026-09-05T08:57:15.527Z

X-Request-ID: 05aed459-9e6a-49e7-b2d5-98bd75a7732d-1788598635

New MediaImage: gid://shopify/MediaImage/39592974516445

The new file reached READY.

We then used the new MediaImage in the same fileUpdate(referencesToAdd) flow for the same product.

UTC: 2026-09-05T08:57:17.690Z

X-Request-ID: 33b8725c-1aae-454e-b49b-dbc8b699ffab-1788598637

This request succeeded and the new MediaImage was attached to the product successfully.

At that point:

  • New MediaImage gid://shopify/MediaImage/39592974516445 was READY

  • fileErrors was empty

  • It was successfully attached to the product

  • Original MediaImage gid://shopify/MediaImage/39592597422301 was still READY with no fileErrors, but remained unusable because of FILE_LOCKED

We are using Admin GraphQL API 2026-04.

This seems to indicate that the original File has an internal pending operation or stale lock that is not reflected by fileStatus or fileErrors.

Is there any API or recommended recovery method to inspect or clear this pending operation, other than deleting and recreating the File?

3

Hey @zhlong, A file can show READY with no fileErrors and still return FILE_LOCKED. The lock is a separate concurrency mechanism from fileStatus.

There is no API field to inspect the lock state or a mutation to clear a stale lock. The lock will clear on its own (typically within approximately an hour), so waiting and retrying is the simplest path.

Your workaround of creating a new file from the same source is a valid approach. Using fileDelete to remove the locked file and then recreating it is another supported option.

4

Hey @zhlong, Checking in to see if the above helped answer your question.