Intervention/image · error · RuntimeException

Unable to set array key, use setWidth() or setHeight()

Error message

Unable to set array key, use setWidth() or setHeight()

What it means

Intervention Image's Size object (the width/height pair returned by $image->size()) implements ArrayAccess for reading only: $size['width'], $size['height'], $size[0] and $size[1] work, but the write side offsetSet() unconditionally throws RuntimeException. The class is intentionally not mutable through array syntax; the message tells you the real mutation API is setWidth()/setHeight(). Any generic code that writes objects via ArrayAccess will always fail here.

Source

Thrown at src/Size.php:482

    public function offsetGet(mixed $offset): mixed
    {
        return match ($offset) {
            0, 'width' => $this->width,
            1, 'height' => $this->height,
            default => throw new RuntimeException('Undefined array key ' . $offset)
        };
    }

    /**
     * {@inheritdoc}
     *
     * @see ArrayAccess::offsetExists()
     *
     * @throws RuntimeException
     */
    public function offsetSet(mixed $offset, mixed $value): void
    {
        throw new RuntimeException('Unable to set array key, use setWidth() or setHeight()');
    }

    /**
     * {@inheritdoc}
     *
     * @see ArrayAccess::offsetExists()
     *
     * @throws RuntimeException
     */
    public function offsetUnset(mixed $offset): void
    {
        throw new RuntimeException('Unable to unset array key');
    }

    /**
     * Show debug info for the current size.
     *
     * @return array<string, int|object>

View on GitHub (pinned to 5598b9e397)

Solutions

1. Replace the array assignment with $size->setWidth(int) and/or $size->setHeight(int), which return the Size instance for chaining.
2. In hydration loops, whitelist the keys and map them explicitly to setWidth()/setHeight() instead of blind offset writes.
3. If you cannot change the third-party writer, wrap the write in try-catch for Intervention\Image\Exceptions\RuntimeException and apply the value through the setter in the catch block.

Example fix

// before
$size = $image->size();
$size['width'] = 800; // RuntimeException: Unable to set array key

// after
$size = $image->size();
$size->setWidth(800);
$size->setHeight(600);

try {
    $size[$key] = $value; // generic ArrayAccess write
} catch (\Intervention\Image\Exceptions\RuntimeException $e) {
    // Size is read-only over array syntax - apply via setter
    match ($key) {
        'width', 0 => $size->setWidth((int) $value),
        'height', 1 => $size->setHeight((int) $value),
        default => throw $e,
    };
}

When it happens

Trigger: Executing any array-style assignment on an Intervention\Image\Size instance: $size['width'] = 800; or $size[0] = 800;. Most often hit in generic hydration/copy loops such as foreach ($dims as $k => $v) { $size[$k] = $v; }, or when porting Intervention Image v2 code that treated sizes like arrays.

Common situations: Porting v2-era scripts to v3's object API; generic object populators (config-to-object mapping, serializer hydration) that write via ArrayAccess; following IDE autocompletion that offers array syntax after seeing offsetGet() work for reads.

Related errors

• Unable to unset array key
• Unable to remove color from palette via array access
• Failed to import color {colorClass} to {class}
• Invalid cmyk() color syntax "{input}"
• Normalized color channel value must be between 0 to 1

AI-assisted analysis of Intervention/image@5598b9e397 (2026-08-23). Data as JSON: /api/errors/bb1c3114fe4760aa. Report an issue: GitHub.