openclaw - 💡(How to fix) Fix SIGILL crash when sharp loads on non-AVX CPUs [1 participants]

Bug Report: SIGILL crash when sharp image processing module loads on non-AVX CPUs

Summary

The OpenClaw gateway crashes with SIGILL (Illegal Instruction) when the sharp native image processing module is loaded on CPUs that don't support AVX instructions (e.g., older AMD CPUs like A6-3420M, pre-2011 Intel CPUs). This happens because sharp's native binaries are compiled with AVX optimizations.

Current Behavior

When any code path calls loadSharp() (e.g., processing images from file paths, vision subagents), the gateway process crashes immediately with:

• SIGILL (status=4/ILL)
• No error message to the user
• Complete gateway restart required

Expected Behavior

OpenClaw should gracefully handle sharp load failures:

1. Detect that sharp cannot be loaded (AVX unavailable, missing library, etc.)
2. Fall back to pass-through mode (send images unoptimized)
3. Log a warning about image optimization being unavailable
4. Continue operating normally

Root Cause Analysis

The loadSharp() function in the OpenClaw source (likely src/media/image-ops.ts or similar) dynamically imports sharp without any error handling. Three of six functions that call loadSharp() lack try/catch protection:

Protected (have try/catch):

• getImageMetadata(buffer) — catches, returns null
• normalizeExifOrientation(buffer) — catches, returns original buffer
• hasAlphaChannel(buffer) — catches, returns false

UNPROTECTED (no try/catch):

• resizeToJpeg(params) — sharp call crashes process
• convertHeicToJpeg(buffer) — sharp call crashes process
• resizeToPng(params) — sharp call crashes process

Reproduction Steps

1. Run OpenClaw on a CPU without AVX support (e.g., AMD A6-3420M)
2. Send an image via file path (e.g., image tool with /path/to/image.jpg)
3. Gateway crashes with SIGILL

Environment

• CPU: AMD A6-3420M (no AVX support)
• OS: Ubuntu 24.04 LTS
• OpenClaw Version: 2026.4.21
• Node.js: v22.22.0
• sharp: @img/sharp-linux-x64 (contains AVX instructions)

Proposed Fix

The fix should be in the OpenClaw source code (not a bundled dist file):

1. Add CPU capability detection before loading sharp, OR add try/catch at the loadSharp() level
2. Ensure ALL sharp callers have try/catch and fall back gracefully
3. Add automatic runtime detection that disables sharp if it crashes on load

Example fix for loadSharp():

async function loadSharp() {
    // Option A: Env var opt-out
    if (process.env.OPENCLAW_IMAGE_BACKEND === "disabled" || process.env.OPENCLAW_IMAGE_BACKEND === "none") {
        throw new Error("Image optimization disabled");
    }
    
    // Option B: Wrap import in try/catch at load time
    try {
        const mod = await import("sharp");
        const sharp = mod.default ?? mod;
        return (buffer) => sharp(buffer, { failOnError: false, limitInputPixels: MAX_IMAGE_INPUT_PIXELS });
    } catch (err) {
        throw new Error(`Failed to load sharp: ${err.message}`);
    }
}

Example fix for resizeToJpeg():

async function resizeToJpeg(params) {
    await assertImagePixelLimit(params.buffer);
    if (prefersSips()) {
        // ... sips path
        return await sipsResizeToJpeg(...);
    }
    try {
        return await (await loadSharp())(params.buffer).rotate().resize({
            width: params.maxSide,
            height: params.maxSide,
            fit: "inside",
            withoutEnlargement: params.withoutEnlargement !== false
        }).jpeg({
            quality: params.quality,
            mozjpeg: true
        }).toBuffer();
    } catch {
        return params.buffer; // Pass through original on failure
    }
}

Same pattern applies to convertHeicToJpeg() and resizeToPng().

Community Workaround

As a temporary fix, users can:

1. Patch their local dist/image-ops-*.js file to add try/catch (bundled dist file)
2. Set OPENCLAW_IMAGE_BACKEND=disabled environment variable
3. Restart the gateway

This disables image optimization but prevents crashes.

Impact

This affects:

• Older AMD CPUs (pre-Bulldozer, pre-2011)
• Some low-power Intel CPUs (older Atom, Celeron)
• Virtual machines without AVX passthrough
• ARM systems running x86 emulation

References

• Similar issue in Node.js ecosystem: https://github.com/lovell/sharp/issues/
• CPU feature detection in Node.js: requires cpuid package or /proc/cpuinfo parsing

Labels: bug, crash, hardware-compatibility, image-processing