Could not load the "sharp" module using the linux-arm64 runtime
#how do i do image processing in convex
steel saffron
random capeBOT
Hi @steel saffron. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:
To do image processing in Convex, the most common approach is to use the sharp library within a Node.js action. However, there are some important caveats and troubleshooting steps, especially regarding platform compatibility and bundling:
1. Use Node.js Actions
Image processing libraries like sharp require the Node.js runtime. You must declare your function as an action (not a mutation or query) and use the "use node" directive at the top of your file.
"use node";
import { internalAction } from "./_generated/server";
import { v } from "convex/values";
import sharp from "sharp";
export const getImageMetadata = internalAction({
args: { url: v.string() },
handler: async (ctx, { url }) => {
const response = await fetch(url);
if (!response.ok) throw new Error("Image not found");
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(arrayBuffer);
return await sharp(buffer).metadata();
},
});
This example fetches an image, processes it with sharp, and returns metadata. You can adapt it for resizing, format conversion, etc.
See Discord example
2. Declare sharp as an External Package
In your convex.json, add sharp to the externalPackages list under the node key:
{
"node": {
"externalPackages": ["sharp"]
}
}
3. Troubleshooting: Platform Compatibility
The error you encountered (Could not load the "sharp" module using the linux-arm64 runtime) is related to native dependencies and platform-specific binaries. Convex runs your code on its servers (often linux-arm64), so you must ensure sharp is installed with the correct binaries.
- Try downgrading to sharp version
0.33.5, which has been reported to work for others. - Install sharp with platform-specific flags:
npm install --os=linux --cpu=arm64 sharp - If using pnpm or another package manager, ensure it supports multi-platform installations.
- See the sharp installation docs for more details.
See Discord troubleshooting discussion
4. Alternative: Use a CDN or Cloudflare Images
If you want a simpler or more scalable solution, consider using the Convex R2 component with Cloudflare Images API and CDN for image resizing and optimization. This offloads processing from your backend and leverages a CDN for delivery.
Reference
Summary:
- Use Node.js actions with
"use node"and declare sharp as an external package. - Ensure sharp is installed for the linux-arm64 platform.
- If you continue to have issues, try sharp@0.33.5 or use a CDN-based solution.