How to Fix MissingSharp Error in Astro.js on Vercel

TL;DR

Install Sharp and configure sharpImageService in your Astro config. This resolves the [MissingSharp] Could not find Sharp error on Vercel and other platforms that don't bundle Sharp by default.

The Error

You run astro build or deploy to Vercel, and the build fails with:

[MissingSharp] Could not find Sharp.
Please install Sharp (`sharp`) manually into your project.

This is one of the most common Astro deployment errors. It works locally but fails on Vercel — a classic "works on my machine" problem.

You'll see this error in:

• Vercel build logs during deployment
• astro build output in CI/CD pipelines
• Any environment where Sharp's native binaries aren't available

Quick Solution

Two steps — configure the image service and install Sharp:

import { defineConfig, sharpImageService } from 'astro/config';

export default defineConfig({
  image: {
    service: sharpImageService(),
  },
});

# Install Sharp as a direct project dependency
pnpm add sharp

Verify the fix locally before deploying:

# Build locally to confirm the error is resolved
pnpm run build

Deploy again. The error is gone.

Why This Happens

Sharp is a native Node.js image processor that Astro uses for image optimization at build time. It converts, resizes, and compresses images through the <Image /> component.

The key issue is that Sharp includes platform-specific native binaries (C/C++). In local development, Sharp is resolved from Astro's own internal dependencies — your OS already has the matching binary. But on Vercel and other CI/CD platforms, the build environment may not have the correct Sharp binary for its architecture.

Adding Sharp as a direct dependency with pnpm add sharp ensures that your package manager installs the correct platform-specific binary during the build step. Instead of relying on Astro's transitive dependency, Sharp becomes a first-class dependency in your project. This is especially important with strict package managers like pnpm that don't hoist transitive dependencies by default.

For more details, see the MissingSharp error reference and the original GitHub issue #5253.

Common Variations

The MissingSharp error isn't the only image issue you'll hit in Astro. Here are three related errors and their fixes.

MissingImageDimension

[MissingImageDimension] Missing width and height attributes

This happens with remote or external images. Astro can't determine dimensions at build time for URLs, so you must provide them:

// ❌ Missing dimensions for remote image
<Image src="https://example.com/photo.jpg" alt="Photo" />

// ✅ Explicit width and height for remote images
<Image
  src="https://example.com/photo.jpg"
  width={800}
  height={600}
  alt="Photo"
/>

RemoteImageNotAllowed

[RemoteImageNotAllowed] Remote image is not allowed

Astro blocks remote images from domains not in your allowlist. Add the domain to your config:

import { defineConfig, sharpImageService } from 'astro/config';

export default defineConfig({
  image: {
    service: sharpImageService(),
    domains: ['example.com', 'cdn.example.com'],
  },
});

ImageMissingAlt

[ImageMissingAlt] Image missing required "alt" property

Astro enforces accessibility. Every <Image /> needs an alt attribute — use alt="" for purely decorative images:

// ❌ No alt attribute
<Image src={hero} />

// ✅ Descriptive alt text
<Image src={hero} alt="Dashboard showing analytics overview" />

Astro Image Best Practices

• Use <Image /> instead of <img> — Astro's component handles optimization, format conversion, and lazy loading automatically
• Use the densities prop for responsive DPI support — densities={[1, 2]} generates 1x and 2x variants
• Leave quality at the default — Astro's defaults balance size and clarity well. Override only when you need lossless (quality="max") or aggressive compression
• Allowlist domains for remote images — add them to image.domains and always provide width + height
• Test astro build locally before deploying — catch image errors early instead of debugging failed Vercel builds
• Configure global Sharp defaults (Astro 6.1+) — set codec-specific options once in your config instead of on every image:

import { defineConfig, sharpImageService } from 'astro/config';

export default defineConfig({
  image: {
    service: sharpImageService({
      webp: { quality: 80 },
      avif: { quality: 65 },
    }),
  },
});

Read more in the Astro Image docs.

Related Articles

• Astro Framework Guide — comprehensive introduction to Astro
• Build a Link Tree with Astro.js — the project where I first hit this error