Fix: Missing Twitter card
Without twitter:card defined in your HTML, links shared on X (Twitter) render as plain text URLs. Twitter's crawler (Twitterbot/1.0) requires this specific meta tag to activate rich media previews. If it is missing, you get no image, no title, and no description, regardless of how meticulously you configured your Open Graph tags.
A plain text URL commands a fraction of the click-through rate compared to a rich preview. A summary_large_image card occupies roughly 50% of the vertical viewport on mobile devices, creating a massive, clickable surface area for your content. Indxel flags missing Twitter cards via the twitter-card rule. It carries a severity weight of 4/100, reflecting the direct traffic loss associated with broken social sharing.
Twitter's fallback behavior is notoriously strict. While the platform will read og:title, og:description, and og:image if the specific twitter:title equivalents are missing, it will not render the card at all unless <meta name="twitter:card"> is explicitly present in the <head>. You must define the presentation layer.
How do you detect a missing Twitter card?
Run npx indxel check against your local build or production URL to scan for the twitter-card warning. The CLI outputs the exact routes missing the metadata, formatting the issues line-by-line with the corresponding rule ID.
$ npx indxel check http://localhost:3000
Validating 47 pages...
/blog/understanding-react-compiler
warning twitter-card Missing twitter:card in metadata
warning missing-og-description Missing Open Graph description
/pricing
warning twitter-card Missing twitter:card in metadata
✖ 3 problems (0 errors, 3 warnings)
Total Score: 96/100The twitter-card rule is a warning by default, meaning it will not fail your CI pipeline unless you configure Indxel to fail on warnings or enforce a minimum score of 100/100.
How do you fix a missing Twitter card?
Add the twitter object to your Next.js metadata export or insert <meta name="twitter:card" content="summary_large_image"> directly into your HTML head.
Next.js App Router
In Next.js 13+, developers frequently configure the openGraph object and assume it covers all social platforms. It does not. You must explicitly define the twitter object in your Metadata export.
Here is the bad pattern that triggers the Indxel warning:
// app/blog/[slug]/page.tsx
import { Metadata } from 'next';
// BAD: Open Graph is set, but Twitter is missing
export const metadata: Metadata = {
title: 'Understanding React Compiler',
description: 'A deep dive into React Forget.',
openGraph: {
title: 'Understanding React Compiler',
description: 'A deep dive into React Forget.',
images: ['/images/react-compiler-og.png'],
},
};Fix this by adding the twitter property. Set the card type to summary_large_image to ensure a full-width image preview.
// app/blog/[slug]/page.tsx
import { Metadata } from 'next';
// GOOD: Twitter card is explicitly defined
export const metadata: Metadata = {
title: 'Understanding React Compiler',
description: 'A deep dive into React Forget.',
openGraph: {
title: 'Understanding React Compiler',
description: 'A deep dive into React Forget.',
images: ['/images/react-compiler-og.png'],
},
twitter: {
card: 'summary_large_image',
title: 'Understanding React Compiler',
description: 'A deep dive into React Forget.',
images: ['/images/react-compiler-og.png'],
creator: '@yourhandle',
},
};Next.js Pages Router
If you are maintaining a Pages Router application, use next/head to inject the raw meta tags.
// pages/blog/[slug].tsx
import Head from 'next/head';
export default function BlogPost({ post }) {
return (
<>
<Head>
<title>{post.title}</title>
<meta property="og:title" content={post.title} />
<meta property="og:image" content={post.coverImage} />
{/* Fix: Explicitly add the Twitter card tag */}
<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:site" content="@yourcompany" />
<meta name="twitter:creator" content="@authorhandle" />
</Head>
<article>...</article>
</>
);
}The Indxel SDK approach
Duplicating title, description, and image URLs between the openGraph and twitter objects creates maintenance overhead and invites desync bugs. Use the Indxel SDK's createMetadata utility to automatically generate fully compliant Twitter tags from your base configuration.
// app/layout.tsx
import { createMetadata } from '@indxel/sdk';
export const metadata = createMetadata({
title: 'My SaaS Application',
description: 'Ship faster with our API.',
image: '/og-image.png',
twitterHandle: '@mysaas',
});This single function call resolves to 14 distinct meta tags, ensuring twitter:card, twitter:site, and twitter:image are always present and perfectly aligned with your Open Graph data.
How do you prevent missing Twitter cards in CI?
Add npx indxel check --ci to your build script or GitHub Actions workflow to fail the build if a page is missing Twitter metadata.
To prevent regressions, configure your CI pipeline to catch missing metadata before it merges to main. You can enforce this globally or run it specifically on changed files using the --diff flag.
Vercel build configuration
Modify your build command in package.json to run the Indxel check alongside your standard Next.js build. This adds roughly 2 seconds to your build time but guarantees no page ships without social metadata.
{
"scripts": {
"dev": "next dev",
"build": "next build && npx indxel check .next --ci",
"start": "next start"
}
}GitHub Actions
For a stricter setup, isolate the check in your CI/CD pipeline. This workflow runs Indxel against your preview deployment.
name: SEO Validation
on: [pull_request]
jobs:
validate-seo:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install dependencies
run: npm ci
- name: Run Indxel SEO Check
run: npx indxel check ${{ github.event.pull_request.head.repo.html_url }} --diff
env:
INDXEL_TOKEN: ${{ secrets.INDXEL_TOKEN }}
INDXEL_FAIL_ON: "twitter-card,missing-og-image"Use the INDXEL_FAIL_ON environment variable to elevate specific warnings (like twitter-card) to errors in your CI environment, forcing the pipeline to fail immediately if the rule is violated.
What are the edge cases for Twitter cards?
The most common edge cases include using relative URLs for images, forgetting to set the metadataBase in Next.js, and serving images larger than 5MB.
Relative vs Absolute URLs
Twitter's crawler cannot resolve relative image paths. If your twitter:image is set to /images/cover.png, Twitterbot will fail to fetch it, resulting in a text-only card. Next.js App Router handles this automatically only if you define metadataBase.
// app/layout.tsx
import { Metadata } from 'next';
export const metadata: Metadata = {
// Required for Next.js to convert relative image paths to absolute URLs
metadataBase: new URL('https://indxel.com'),
twitter: {
card: 'summary_large_image',
},
};Dynamic routes missing data
When fetching data for dynamic routes (app/blog/[slug]/page.tsx), network failures or missing database fields can result in empty metadata fields. If post.coverImage is undefined, Next.js omits the twitter:image tag entirely. Always provide a fallback image.
export async function generateMetadata({ params }): Promise<Metadata> {
const post = await getPost(params.slug);
return {
title: post.title,
twitter: {
card: 'summary_large_image',
images: [post.coverImage || '/default-twitter-card.png'],
},
};
}Image format and size restrictions
Twitter strictly enforces image constraints. The image must be less than 5MB and formatted as JPG, PNG, WEBP, or GIF. SVG files are not supported. If you pass an SVG to twitter:image, the card will fail silently.
If you are using Next.js ImageResponse (edge-generated OG images), the output is automatically a PNG, which perfectly satisfies Twitter's format requirements.
What are related Indxel rules?
The twitter-card rule frequently triggers alongside missing-og-image, missing-og-title, and missing-og-description.
missing-og-image: Validates the presence and HTTP status of your Open Graph image.missing-og-title: Ensures every page has a specific Open Graph title.missing-og-description: Checks for a dedicated Open Graph description string.invalid-metadata-base: Flags relative Open Graph or Twitter image URLs when no fallback domain is configured.
Frequently Asked Questions
What is the difference between summary and summary_large_image?
summary displays a 144x144px square thumbnail next to your text. summary_large_image renders a full-width image above the title. Use summary_large_image for articles and landing pages to maximize click-through rates.
Does Twitter fall back to Open Graph tags if twitter tags are missing?
Twitter falls back to og:title, og:description, and og:image if the specific twitter: equivalents are missing, but it strictly requires the twitter:card tag to activate the rich preview.
Why is my Twitter card not updating after I deployed the fix?
Twitter caches card data for up to 7 days. You must use the Twitter Card Validator (now integrated into the X Post composer) to fetch the latest metadata and clear the cache. Simply paste your URL into a new post draft on X to force a recrawl.
Can I use SVG for my Twitter card image?
No, Twitter does not support SVG for card images. You must serve your images in JPG, PNG, WEBP, or GIF format, keeping the file size under 5MB and the dimensions close to 1200x630px for large cards.
Frequently asked questions
What's the difference between summary and summary_large_image?
summary shows a small square thumbnail next to the title. summary_large_image shows a full-width image above the title. Use summary_large_image for most pages — it gets more clicks.