How to Fix: Open graph image. Failed to parse linear-gradient with oklch values.

Your Open Graph image generation is crashing because the parser handling CSS gradients in the OG rendering pipeline cannot currently parse oklch() color values inside linear-gradient(). The page may render fine in the browser, but the server-side image renderer used for social cards is far more limited than a modern browser CSS engine.

Understanding the Root Cause

This issue happens in the Open Graph image rendering layer, not necessarily in your normal app UI. When you visit the route that generates the OG image, the framework uses a server-side renderer that supports only a subset of CSS. While browsers increasingly support OKLCH and other modern color functions, the image generation stack often relies on a stricter parser.

In this bug, a declaration similar to a gradient using linear-gradient(… oklch(…) …) is passed into the OG image renderer. That parser fails before rendering because it does not understand OKLCH tokens inside gradient color stops. As a result, the image generation route throws an error instead of returning a valid image.

Typical failing code looks like this:

background: linear-gradient(135deg, oklch(62% 0.25 264), oklch(70% 0.18 320));

Why this is confusing:

• The same CSS may work perfectly in the browser.
• The failure appears only on routes using ImageResponse or equivalent OG image generation APIs.
• The parser error points at the gradient, even though the deeper cause is unsupported color syntax.

The practical root cause is simple: OG image CSS support lags behind browser CSS support.

Step-by-Step Solution

The safest fix is to replace oklch() colors in gradients with broadly supported formats such as hex, rgb(), or hsl(). If you want to keep OKLCH in your regular app, use a separate fallback for the Open Graph image route.

1. Find the OG image component or route

Look for code related to social image generation, usually in files such as:

• opengraph-image.tsx
• twitter-image.tsx
• route.tsx using ImageResponse

2. Identify the unsupported gradient

You will usually find a style block like this:

export default function Image() {
  return (
    <div
      style={{
        background: "linear-gradient(135deg, oklch(62% 0.25 264), oklch(70% 0.18 320))",
      }}
    >
      Hello
    </div>
  );
}

3. Replace OKLCH with supported color values

Convert the colors to hex or rgb(). For example:

export default function Image() {
  return (
    <div
      style={{
        background: "linear-gradient(135deg, #6366f1, #d946ef)",
      }}
    >
      Hello
    </div>
  );
}

You can also use RGB:

export default function Image() {
  return (
    <div
      style={{
        background: "linear-gradient(135deg, rgb(99, 102, 241), rgb(217, 70, 239))",
      }}
    >
      Hello
    </div>
  );
}

4. If your design system uses OKLCH globally, create an OG-safe palette

If your app uses modern tokens such as oklch() through Tailwind, CSS variables, or a theme system, avoid reusing those values directly in the OG image route. Instead, define a separate mapping:

const ogColors = {
  start: "#6366f1",
  end: "#d946ef",
  text: "#ffffff",
};

export default function Image() {
  return (
    <div
      style={{
        background: `linear-gradient(135deg, ${ogColors.start}, ${ogColors.end})`,
        color: ogColors.text,
      }}
    >
      Hello
    </div>
  );
}

5. Restart and retest the route

After updating the gradient:

npm run dev

Then open your OG test route again and verify the image renders without parser errors.

6. Optional: keep OKLCH in the browser, fallback in OG rendering

If you want modern colors in the UI but compatibility in OG generation, split the styles by runtime:

const browserGradient = "linear-gradient(135deg, oklch(62% 0.25 264), oklch(70% 0.18 320))";
const ogGradient = "linear-gradient(135deg, #6366f1, #d946ef)";

Use the OG-safe gradient only in the image generator.

Working example for an Open Graph image route

import { ImageResponse } from "next/og";

export const size = {
  width: 1200,
  height: 630,
};

export const contentType = "image/png";

export default function Image() {
  return new ImageResponse(
    (
      <div
        style={{
          display: "flex",
          width: "100%",
          height: "100%",
          alignItems: "center",
          justifyContent: "center",
          background: "linear-gradient(135deg, #6366f1, #d946ef)",
          color: "white",
          fontSize: 64,
          fontWeight: 700,
        }}
      >
        Open Graph Image
      </div>
    ),
    {
      ...size,
    }
  );
}

This avoids unsupported OKLCH gradient parsing while preserving the same visual intent.

Common Edge Cases

• CSS variables resolve to OKLCH: Even if your gradient looks simple, a variable like var(--brand) may expand to an unsupported oklch(...) value during rendering.
• Tailwind theme colors: Newer Tailwind setups may emit OKLCH-based tokens. If those tokens are used in OG images, the parser can still fail.
• Other unsupported CSS functions: The OG renderer may also reject advanced color functions, filters, blend modes, or newer layout features.
• Class-based styles not behaving as expected: Some OG image workflows are more reliable with inline styles than with external CSS classes, especially for critical visual properties like background gradients.
• Transpiled design tokens: A token pipeline may convert brand colors to OKLCH automatically. If so, hardcoded fallback values may be necessary specifically for image generation.
• Different behavior in dev and production: A local dev environment might expose the issue differently than a deployed runtime, depending on renderer version and dependency resolution.

FAQ

Can I use oklch() anywhere in my app?

Yes. The problem is usually limited to the Open Graph image renderer, not the entire application. Regular browser-rendered pages may support OKLCH just fine.

Why does the browser render the gradient but the OG route fails?

Because they use different rendering engines. Your browser has modern CSS support, while the server-side image generation parser supports only a subset of CSS syntax.

What is the best long-term fix?

For now, use fallback color formats like hex or RGB in OG image routes. If upstream support is added later, you can switch back to OKLCH after confirming the renderer accepts it.

If you are maintaining a shared design system, the most robust approach is to treat Open Graph image styling as a compatibility-sensitive surface: keep the visuals simple, prefer widely supported CSS, and avoid modern color functions unless you have verified support in the image generation stack.