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

Unable to set color via array access, use addColor() instead

Error message

Unable to set color via array access, use addColor() instead

What it means

Palette implements ArrayAccess for reading only; offsetSet() unconditionally throws NotSupportedException to direct writes to the accepted API addColor() (src/Colors/Palette.php:68-71). offsetUnset() is disabled for the same reason, since bins are keyed by color hashes and hold occurrence counts that offsetSet could not maintain.

Source

Thrown at src/Colors/Palette.php:70

     * {@inheritdoc}
     *
     * @see ArrayAccess::offsetGet()
     */
    public function offsetGet(mixed $offset): ColorInterface
    {
        return $this->toArray()[$offset];
    }

    /**
     * {@inheritdoc}
     *
     * @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>

View on GitHub (pinned to 5598b9e397)

Solutions

1. Use $palette->addColor($color, $count) for every insert
2. Build a new palette from scratch: new Palette([$colorA, $colorB]) which routes through addColor()
3. Use $palette->filter()/map() to derive modified palettes instead of in-place writes
4. To remove entries, create a filtered palette rather than unset($palette[$i]) (also disabled)

Example fix

// before
$palette = $image->extractColorPalette();
$palette[0] = $myColor; // NotSupportedException

// after
$palette = $image->extractColorPalette();
$palette->addColor($myColor); // optionally with count: addColor($myColor, 3)

// Detect palette-like collections and route writes to the supported API
if ($palette instanceof Intervention\Image\Interfaces\PaletteInterface) {
    $palette->addColor($color, $count);
} else {
    $palette[] = $color; // plain array path
}

function addColorToPalette(PaletteInterface $palette, ColorInterface $color, int $count = 1): PaletteInterface
{
    return $palette->addColor($color, $count);
}

When it happens

Trigger: Executing $palette[0] = $color, $palette[] = $color, or any ArrayAccess assignment on a Palette, e.g. one returned by ColorExtractor or built from an image.

Common situations: Treating Palette like a plain array during refactors (foreach + assignment, array_map-style rebuilds); generic collection code that writes via offsetSet on anything ArrayAccess.

Related errors

• Unable to remove color from palette via array access
• Failed to invert color
• 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/20c68d7223076f17. Report an issue: GitHub.