Intervention/image · error · Intervention\Image\Exceptions\NotSupportedException

Unable to remove color from palette via array access

Error message

Unable to remove color from palette via array access

What it means

Palette implements ArrayAccess, but only for reading: offsetGet()/offsetExists() work while offsetSet() and offsetUnset() always throw NotSupportedException. Colors are stored internally in Bin objects keyed by a content hash and carrying occurrence counts, so removing an entry with unset() would bypass that bookkeeping. The library requires you to derive a new palette instead of mutating keys.

Source

Thrown at src/Colors/Palette.php:82

     * @see ArrayAccess::offsetSet()
     *
     * @throws NotSupportedException
     */
    public function offsetSet(mixed $offset, mixed $value): void
    {
        throw new NotSupportedException('Unable to set color via array access, use addColor() instead');
    }

    /**
     * {@inheritdoc}
     *
     * @see ArrayAccess::offsetUnset()
     *
     * @throws NotSupportedException
     */
    public function offsetUnset(mixed $offset): void
    {
        throw new NotSupportedException('Unable to remove color from palette via array access');
    }

    /**
     * Implementation of IteratorAggregate.
     *
     * @return Traversable<ColorInterface>
     */
    public function getIterator(): Traversable
    {
        return new ArrayIterator($this->toArray());
    }

    /**
     * {@inheritdoc}
     *
     * @see PaletteInterface::addColor()
     */
    public function addColor(ColorInterface $color, int $count = 1): self

View on GitHub (pinned to 5598b9e397)

Solutions

1. Use $palette->filter(callable) to build a new palette that excludes the unwanted colors
2. Use $palette->slice($offset, $length) to keep or drop a contiguous range of bins
3. Rebuild manually: new Palette(array_values(array_diff($palette->toArray(), [$color])))
4. If a generic unset() path cannot be removed, catch Intervention\Image\Exceptions\NotSupportedException and fall back to filter()

Example fix

// before
unset($palette[0]); // NotSupportedException: Unable to remove color from palette via array access

// after
$palette = $palette->slice(1);

try {
    unset($palette[$index]);
} catch (\Intervention\Image\Exceptions\NotSupportedException $e) {
    $palette = $palette->filter(fn ($color) => !
        $palette->toArray()[$index]->toHex() === $color->toHex()
    ); // or rebuild via slice()/toArray()
}

When it happens

Trigger: unset($palette[0]) or unset($palette['somekey']) on any Intervention\Image\Colors\Palette instance, e.g. one returned by ColorExtractor or $image->extractPalette(...).

Common situations: Treating the palette like a plain array because it implements ArrayAccess and is foreach-iterable; porting array-manipulation code that previously ran on plain color arrays; refactoring older Intervention v2 code where extracted colors were stored in normal arrays.

Related errors

• Unable to set color via array access, use addColor() instead
• Failed to apply {class}, unable to process quantization
• Unable to set array key, use setWidth() or setHeight()
• Unable to unset array key
• Failed to import color {colorClass} to {class}

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