[BUG] collectionUpdate silently ignores altText: null can't clear a collection image's alt text

GraphQL Admin API Troubleshooting
1

API version: 2026-07

Steps to reproduce

1. Create a collection with an image that has alt text set, e.g.:

mutation {
  collectionUpdate(collection: {
    id: "gid://shopify/Collection/…"
    image: { src: "https://cdn.shopify.com/…/file.jpg", altText: "some alt text" }
  }) {
    collection { image { id url altText } }
    userErrors { field message }
  }
}

2. Send a follow-up collectionUpdate intended to clear the alt text, either shape:

a) id-only, no src
image: { id: "gid://shopify/CollectionImage/…", altText: null }

b) resending the same src
image: { src: "https://cdn.shopify.com/…/file.jpg", altText: null }

c) alt-text-only, no id, no src
image: { altText: null }

Result: no userErrors, request succeeds, altText on the returned/refetched image is unchanged.

Same outcome when replacing with an empty string: altText: ""

Expected

altText is cleared (null) on the collection image, same as any other field explicitly set to null in a partial-update mutation.

Actual

All three shapes (id-only, src-resend, alt-text-only) behave identically: collectionUpdate accepts altText: null without error but never applies it. There appears to be no collectionUpdate input shape that clears a collection image’s alt text while keeping the image.

The only way I found is to clear the image and send a new one - which as a consequence will create a new image resource in shopify.

2

Hi @Donal-Shopify I see you put an emoji on my message indicating that you may be investigating in this issue.

Before you dive deeper: actually the issue is not just with the grpahql API. It’s also happening on the native shopify collection UI.

If I empty the alt text:

image
image346×229 41.6 KB

image
image940×1131 103 KB

then I click “done” and “save”. The alt text comes back to what it was before.

3

Hey @Soufiane_Ghzal, yeah I’m taking a look right now. Thanks for that additional context - I’ll follow up here once I’ve fully replicated and taken a look at how this is supposed to work. Feel free to keep adding more details and I’ll take them into account!

4

Hey @Soufiane_Ghzal - I can replicate the issue by clearing the alt text in the admin which brings the old text back on reload, but a direct collectionUpdate call on the same store and collection clears it fine for me.

So the very same inputs get a different result depending on the path, which I’m now working on pinning down.

Since I can’t repro via API, could you share an x-request-id header from one of your reproductions? With it I should be able to nail down the exact cause and open an issue to get it fixed. Thanks as always for your help with this!

5

Hi @Donal-Shopify thank you for investigating. Here are a bunch of samples including the query the variables, the request id and the respoinse:

using id and null

query: #graphql
    mutation CollectionUpdate($collection: CollectionUpdateInput!) {
      collectionUpdate(collection: $collection) {
        collection { image { id url altText } }
        userErrors { field message }
      }
    }
variables: {
  "collection": {
    "id": "gid://shopify/Collection/662345941176",
    "image": {
      "id": "gid://shopify/CollectionImage/1863531069624",
      "altText": null
    }
  }
}
x-request-id: 0c20a9c2-1fdf-45e7-aacf-e1aed23e0e2f-1790075005
response: {
  "data": {
    "collectionUpdate": {
      "collection": {
        "image": {
          "id": "gid://shopify/CollectionImage/1863531069624",
          "url": "https://cdn.shopify.com/s/files/1/0977/2145/0680/collections/test-api-image-1790075000654.png?v=1790075004",
          "altText": "before clear"
        }
      },
      "userErrors": []
    }
  }
}

Using id and empty string

query: #graphql
    mutation CollectionUpdate($collection: CollectionUpdateInput!) {
      collectionUpdate(collection: $collection) {
        collection { image { id url altText } }
        userErrors { field message }
      }
    }
variables: {
  "collection": {
    "id": "gid://shopify/Collection/662345941176",
    "image": {
      "id": "gid://shopify/CollectionImage/1863531069624",
      "altText": ""
    }
  }
}
x-request-id: 20539009-922d-407f-baf9-b7c1e069f583-1790075005
response: {
  "data": {
    "collectionUpdate": {
      "collection": {
        "image": {
          "id": "gid://shopify/CollectionImage/1863531069624",
          "url": "https://cdn.shopify.com/s/files/1/0977/2145/0680/collections/test-api-image-1790075000654.png?v=1790075004",
          "altText": "before clear"
        }
      },
      "userErrors": []
    }
  }
}

Using src and null

query: #graphql
    mutation CollectionUpdate($collection: CollectionUpdateInput!) {
      collectionUpdate(collection: $collection) {
        collection { image { id url altText } }
        userErrors { field message }
      }
    }
variables: {
  "collection": {
    "id": "gid://shopify/Collection/662345941176",
    "image": {
      "src": "https://cdn.shopify.com/s/files/1/0977/2145/0680/collections/test-api-image-1790075000654.png?v=1790075004",
      "altText": null
    }
  }
}
x-request-id: ff8fce74-8043-41a3-bad0-743dea649198-1790075006
response: {
  "data": {
    "collectionUpdate": {
      "collection": {
        "image": {
          "id": "gid://shopify/CollectionImage/1863531069624",
          "url": "https://cdn.shopify.com/s/files/1/0977/2145/0680/collections/test-api-image-1790075000654.png?v=1790075004",
          "altText": "before clear"
        }
      },
      "userErrors": []
    }
  }
}

Using alt text only and null

query: #graphql
    mutation CollectionUpdate($collection: CollectionUpdateInput!) {
      collectionUpdate(collection: $collection) {
        collection { image { id url altText } }
        userErrors { field message }
      }
    }
variables: {
  "collection": {
    "id": "gid://shopify/Collection/662345941176",
    "image": {
      "altText": null
    }
  }
}
x-request-id: 5b662336-9a2d-4844-ad98-71b6d359f591-1790075008
response: {
  "data": {
    "collectionUpdate": {
      "collection": {
        "image": {
          "id": "gid://shopify/CollectionImage/1863531069624",
          "url": "https://cdn.shopify.com/s/files/1/0977/2145/0680/collections/test-api-image-1790075000654.png?v=1790075004",
          "altText": "before clear"
        }
      },
      "userErrors": []
    }
  }
}
6

Hi @Donal-Shopify This is seemingly fixed?

7

Hi @Soufiane_Ghzal, thanks for waiting to hear back from me - I was out of office for a few days so appreciate you updating the thread!

Just to round out how it currently works for anyone who might find this thread in the future, passing altText as null or an empty string clears the stored text, while omitting the altText field leaves the existing value untouched, so reference the image by id to keep it. The collectionUpdate docs cover the input shapes.

Thanks again for reporting the issue here, we do appreciate iot.