PHPOffice/PhpSpreadsheet · error · PhpOffice\PhpSpreadsheet\Exception

Chart renderer must implement PhpOffice\PhpSpreadsheet\Chart

Error message

Chart renderer must implement PhpOffice\PhpSpreadsheet\Chart\Renderer\IRenderer

What it means

Settings::setChartRenderer() registers the class used to render charts; the guard is is_a($rendererClassName, IRenderer::class, true), so the string must name an existing class implementing Chart\Renderer\IRenderer. Note the bundled implementation Chart\Renderer\JpGraph additionally requires the jpgraph library to be installed, otherwise rendering later fails with a different error ('JpGraph Library not included').

Source

Thrown at src/PhpSpreadsheet/Settings.php:56

    {
        return Calculation::getInstance()->setLocale($locale);
    }

    public static function getLocale(): string
    {
        return Calculation::getInstance()->getLocale();
    }

    /**
     * Identify to PhpSpreadsheet the external library to use for rendering charts.
     *
     * @param class-string<IRenderer> $rendererClassName Class name of the chart renderer
     *    eg: PhpOffice\PhpSpreadsheet\Chart\Renderer\JpGraph
     */
    public static function setChartRenderer(string $rendererClassName): void
    {
        if (!is_a($rendererClassName, IRenderer::class, true)) {
            throw new Exception('Chart renderer must implement ' . IRenderer::class);
        }

        self::$chartRenderer = $rendererClassName;
    }

    public static function unsetChartRenderer(): void
    {
        self::$chartRenderer = null;
    }

    /**
     * Return the Chart Rendering Library that PhpSpreadsheet is currently configured to use.
     *
     * @return null|class-string<IRenderer> Class name of the chart renderer
     *    eg: PhpOffice\PhpSpreadsheet\Chart\Renderer\JpGraph
     */
    public static function getChartRenderer(): ?string
    {

View on GitHub (pinned to 65b080eef4)

Solutions

Use the constant, not a literal: Settings::setChartRenderer(\PhpOffice\PhpSpreadsheet\Chart\Renderer\JpGraph::class)
Install the dependency: composer require jpgraph/jpgraph, or call Settings::unsetChartRenderer() if charts are not needed
For custom renderers, implement every method of Chart\Renderer\IRenderer (render(), etc.) and reference the class via ClassName::class
Clear the renderer in test teardown to avoid leaking state between tests

Example fix

// before
\PhpOffice\PhpSpreadsheet\Settings::setChartRenderer('JpGraph'); // throws

// after
\PhpOffice\PhpSpreadsheet\Settings::setChartRenderer(
    \PhpOffice\PhpSpreadsheet\Chart\Renderer\JpGraph::class
); // + composer require jpgraph/jpgraph

Defensive patterns

Strategy: validation

Validate before calling

use PhpOffice\PhpSpreadsheet\Chart\Renderer\IRenderer;
use PhpOffice\PhpSpreadsheet\Settings;

$renderer = \PhpOffice\PhpSpreadsheet\Chart\Renderer\JpGraph::class;
if (is_a($renderer, IRenderer::class, true)) {
    Settings::setChartRenderer($renderer);
}

Type guard

function isValidRendererClass(string $class): bool
{
    return is_a($class, \PhpOffice\PhpSpreadsheet\Chart\Renderer\IRenderer::class, true);
}

Try / catch

try {
    Settings::setChartRenderer($rendererClass);
} catch (\PhpOffice\PhpSpreadsheet\Exception $e) {
    // fall back to exporting without rendered charts
    Settings::unsetChartRenderer();
}

Prevention

Reference renderers via ClassName::class, never string literals
composer require jpgraph/jpgraph when enabling the bundled renderer
Implement all IRenderer methods in custom renderers
unsetChartRenderer() in test teardown to avoid cross-test leakage

When it happens

Trigger: Settings::setChartRenderer('JpGraph') — wrong/missing namespace; a class name with a typo or not autoloadable (is_a returns false for nonexistent classes); a custom renderer that does not implement the IRenderer interface; passing an instance instead of a class-string is fine only if it implements IRenderer.

Common situations: First-time chart export setup without composer-requiring jpgraph; copying PHPExcel-era examples; renaming of renderer classes across major versions; test bootstrap left over from another project.

Related errors

AI-assisted analysis of PHPOffice/PhpSpreadsheet@65b080eef4 (2026-08-17). Data as JSON: /api/errors/8eb4ec6ec2690418. Report an issue: GitHub.