Skip to main content

Troubleshoot storefront thumbnail rendering failures

Updated May 15, 2026

A five-hypothesis playbook for grey or blank product thumbnails when the API data is healthy

Use this guide when supporters report grey or blank thumbnails on a shop, but the API confirms the underlying data is intact. A typical confirmation looks like 120 product images on the CDN, 84 variants reporting Available, and product status set to Public. The failure is happening between the CDN response and the supporter's browser, so the next round of checks must move past the data layer.

This playbook orders the five most likely causes from cheapest to investigate to most disruptive. Work through them in order.

Confirm the failure is client-side​

Before opening hypothesis 1, lock in the evidence so the investigation stays focused.

  • API re-verified: every product returns a populated images array (for example, 120 .webp files on the CDN).
  • Variants are all Available (for example, 84 of 84).
  • Product status is Public.
  • Multiple supporters across different devices and browsers see the same grey or blank thumbnails.

If any of these break down, stop. The issue is not client-side and belongs in a different playbook.

Hypothesis 1: Regional CDN block​

A regional or network-level block on the CDN edge can serve a 0-byte response or a connection reset, which renders as a grey placeholder in the browser. The API data looks fine because the API and the CDN are separate origins.

Test it:

  1. Pull one image URL from the API response (for example, https://storage.googleapis.com/fourthwall-images/...webp).
  2. Open it directly in a clean browser tab. Record whether it loads, returns an error, or hangs.
  3. Repeat the same URL from a different network (mobile hotspot, VPN exit in another region, or an internal proxy in a known-good region).
  4. Compare the HTTP status. A 200 from one region and a connection failure from another points to a regional block.

If the regional difference is confirmed, escalate to infrastructure with the failing region, exit IP, and a sample CDN URL. Do not move to hypothesis 2 until this is ruled out.

Hypothesis 2: Recently-flagged shop visibility state​

If the shop has been flagged for review, certain assets can be withheld from rendering even when the API still reports them as Public. The visibility state lives outside the product object, so a healthy API response does not rule this out.

Check the shop visibility state:

  1. Open the shop's internal admin record and look at the visibility flag, not just the product status.
  2. Confirm there is no active review, hold, or restricted-content flag on the account.
  3. Check the audit log for any flag transitions in the last 7 days that could correlate with the report timestamp.

If the shop is in a flagged state, the thumbnails will not render until the flag is cleared. Hand off to the trust and safety queue with the shop ID and the audit-log entry that triggered the flag.

Hypothesis 3: Corrupted variant image generation​

Variant images are generated downstream of the product image and have a separate render pipeline. A corrupted render can leave the API reporting the variant as Available with a valid image URL, while the underlying file is empty, truncated, or pointing at a missing key.

Trigger a re-render:

  1. Pick three to five variants reported as Available across different products.
  2. Fetch their image URLs directly. Note any that return 0 bytes, 404, or a placeholder image.
  3. In the internal product tools, force a variant image re-render for the affected products.
  4. Wait for the regeneration job to complete, then re-fetch the URLs to confirm valid bytes.

If re-rendering fixes the URLs, the original generation job was the root cause. Capture the variant IDs and the original generation timestamp so the platform team can trace why the job produced bad output.

Hypothesis 4: Account-level network or firewall block​

A network rule on the supporter's side (corporate firewall, ISP-level filter, browser extension that blocks third-party domains) can drop CDN requests while leaving the shop HTML intact. This looks identical to a regional CDN block from the supporter's perspective, but the root cause sits on their network, not Fourthwall's.

Confirm the boundary:

  1. Ask the reporter to test the shop on a different network (mobile data, a personal hotspot, or a different ISP).
  2. Ask them to disable browser extensions and retry in an incognito or private window.
  3. Compare the network tab in DevTools: a blocked CDN request will show as (blocked:client), net::ERR_BLOCKED_BY_CLIENT, or net::ERR_BLOCKED_BY_RESPONSE.
  4. If the thumbnails load on a different network or with extensions disabled, the block is account-side.

When the issue is account-side, document the specific network or extension responsible. Send the supporter the standard guidance on whitelisting the CDN domain.

Hypothesis 5: Product-state desync​

A genuine desync between the product state in the API and the storefront cache is the final possibility. The API reports Public with valid variants because the source of truth is correct, but the storefront's cached render still references a stale or invalidated state.

Force a resync:

  1. Compare the product's updated_at timestamp from the API against the storefront's last-cache timestamp.
  2. If the storefront cache is older than the most recent product update, trigger a cache purge for the affected product IDs.
  3. Confirm the storefront re-fetches and re-renders by reloading with cache disabled.
  4. If thumbnails return, log the cache age delta. Repeated desync on the same shop points to a stuck invalidation job.

If a cache purge does not fix the thumbnails, the issue is not a desync. Re-open the playbook from hypothesis 1 with any new evidence collected during testing.

Information to capture before escalation​

Once the playbook is exhausted, hand off with:

  • Shop ID and product IDs with confirmed grey or blank thumbnails.
  • Sample CDN image URL plus the HTTP status returned from the testing region.
  • Confirmation that variants are Available and product status is Public.
  • Region, network type, browser, and extensions for at least one reporter.
  • Audit-log entries from the last 7 days for the shop's visibility state.
  • Timestamps for any forced re-render or cache purge attempted during the investigation.

If you have any questions, do not hesitate to contact us at support@fourthwall.com.

Was this helpful?