octobercms/october · error · SystemException

Dimension is required.

Error message

Dimension is required.

What it means

ReportQueryBuilder::validate() requires a dimension to be set and throws SystemException('Dimension is required.') when $this->dimension is falsy. The dimension is the axis the report groups by (a ReportDimension instance), and every SELECT/GROUP BY expression the builder renders depends on it, so a dimensionless report query cannot be constructed. It is the second guard in validate(), checked right after the table name.

Source

Thrown at modules/dashboard/classes/ReportQueryBuilder.php:665

    }

    //
    // Internal Query Building
    //

    /**
     * validate ensures required properties are set
     *
     * @throws SystemException
     */
    protected function validate(): void
    {
        if (!$this->tableName) {
            throw new SystemException('Table name is required.');
        }

        if (!$this->dimension) {
            throw new SystemException('Dimension is required.');
        }

        if (($this->dateStart || $this->dateEnd) && $this->startTimestamp !== null) {
            throw new SystemException('Cannot use both date range and timestamp filtering.');
        }

        if (!$this->dateStart && $this->startTimestamp === null) {
            throw new SystemException('Either date range or start timestamp is required.');
        }

        if ($this->limit !== null && $this->pagination !== null) {
            throw new SystemException('Cannot use both limit and pagination.');
        }
    }

    /**
     * buildQuery constructs the query builder
     *

View on GitHub (pinned to b608633a7e)

Solutions

1. Set a dimension before building: $builder->setDimension($dataSource->getDimension('status')) using a code the data source actually defines.
2. If the dimension comes from widget/request config, validate the code resolves to a ReportDimension and fail with a clear message or default before calling the builder.
3. Fix the dashboard/widget definition to include a valid dimension code (check spelling/case against the data source's defineDimensions()).
4. In custom data sources, ensure getDimension()/findDimensionByCode covers the code your UI sends.

Example fix

// before
$builder->table('orders')->applyMetrics($metrics);
$rows = $builder->buildQuery()->get();

// after
$dimension = $dataSource->findDimensionByCode('status');
if (!$dimension) {
    throw new ApplicationException('Unknown dimension: status');
}
$builder->table('orders')->setDimension($dimension)->applyMetrics($metrics);
$rows = $builder->buildQuery()->get();

$dimension = $dataSource->findDimensionByCode($code);
if (!$dimension instanceof ReportDimension) {
    throw new InvalidArgumentException("Unknown dimension '{$code}' on this data source.");
}
$builder->setDimension($dimension);

function resolveDimension(ReportDataSourceBase $source, string $code): ?ReportDimension
{
    foreach ($source->getAvailableDimensions() as $dimension) {
        if ($dimension->getCode() === $code) {
            return $dimension;
        }
    }
    return null;
}

When it happens

Trigger: Building a query via ReportQueryBuilder without calling setDimension()/dimension() — e.g. only applying metrics; passing null because the dimension lookup (findDimensionByCode on the data source) failed silently upstream; widget config that omits the 'dimension' key when composing the builder.

Common situations: Dashboard widget configuration missing or misspelling the dimension code so the controller resolves null and forwards it; reordering builder setup code so buildQuery() runs before the dimension is attached; data source that defines metrics but no default dimension.

Related errors

• Invalid configuration. All keys must be non-empty strings an
• The dimension field code cannot be empty.
• Display name cannot be empty.
• Table name is required.
• Cannot find the requested row group.

AI-assisted analysis of octobercms/october@b608633a7e (2026-08-21). Data as JSON: /api/errors/e6c34bff96c5b265. Report an issue: GitHub.