# twitter:image is explicitly configured

- **Pattern:** `ab-001813` (`marketing-social-sharing.twitter-cards.twitter-image-explicit`)
- **Severity:** high
- **Lifecycle:** active
- **Last modified:** 2026-04-18
- **Canonical URL:** https://auditbuffet.com/patterns/ab-001813
- **License:** CC-BY-4.0 — attribute to AuditBuffet Pattern Catalog (https://auditbuffet.com/patterns/ab-001813)

## Why it matters

Twitter/X's fallback to og:image is documented but not universally reliable. When the og:image URL includes query parameters, signed tokens, or CDN paths that require specific headers, Twitter's crawler may silently fail to fetch the image and render the card without a visual. Per the Twitter Cards spec, an explicit `twitter:image` that uses a clean, unconditional HTTPS URL removes this ambiguity. The reference-integrity failure mode is invisible in development: the image works in browsers but fails when crawled by bots, producing cards that show no image in production social shares without any error signal in your logs.

## Severity rationale

High because relying on og:image fallback exposes shares to silent image-fetch failures when CDN URLs use query parameters or conditional access patterns that Twitter's crawler cannot navigate.

## Remediation

Add an explicit `twitter.images` array to your metadata to avoid relying on og:image fallback behavior:

```ts
twitter: {
  card: 'summary_large_image',
  images: ['https://yoursite.com/og-image.png'],
}
```

For dynamic routes, generate the Twitter image URL the same way as the OG image — they can reference the same resource. The explicit declaration ensures Twitter uses the exact URL you specify rather than deriving one from the og:image value. Confirm the referenced URL is a clean absolute HTTPS path with no query parameters.

## Detection

- **ID:** `twitter-image-explicit`
- **Severity:** `high`
- **What to look for:** Check whether `twitter:image` (or `metadata.twitter.images`) is explicitly set, separate from the `og:image`. Twitter/X does fall back to `og:image` if `twitter:image` is absent, but the fallback is not always reliable — especially when the OG image URL includes query parameters or when the image is served from a CDN that requires specific headers. Look for explicit `twitter.images` arrays in metadata exports. Count all instances found and enumerate each.
- **Pass criteria:** `twitter:image` is explicitly set at least in layouts that contain content pages, OR `og:image` is set and the OG image URL is a clean absolute URL (no query parameters, no auth-required path) that Twitter can reliably crawl. At least 1 implementation must be confirmed.
- **Fail criteria:** No `twitter:image` is set anywhere AND `og:image` is either missing or uses a URL pattern that may not be reliably accessible (query-parameterized, path-based auth, signed URL).
- **Skip (N/A) when:** Project type is `api` with no public-facing pages.
- **Detail on fail:** Specify whether the issue is missing entirely or relies on a potentially unreliable OG image URL. Example: `"No twitter:image set and og:image uses a signed CDN URL that Twitter's crawler may not be able to access"`
- **Remediation:** While Twitter does fall back to `og:image`, you avoid a category of sharing failures by being explicit. Add `twitter.images` to your metadata:

  ```ts
  twitter: {
    card: 'summary_large_image',
    images: ['https://yoursite.com/og-image.png'],
  }
  ```

  For dynamic content pages, generate the Twitter image URL the same way as the OG image — they can point to the same resource.

## External references

- external twitter-cards — https://developer.twitter.com/en/docs/twitter-for-websites/cards/overview/markup

Taxons: findability, reference-integrity

HTML version: https://auditbuffet.com/patterns/ab-001813