octobercms/october · error · ApplicationException

Media tags can only be processed for front-end requests.

Error message

Media tags can only be processed for front-end requests.

What it means

MediaView is the front-end markup extension that replaces data-audio/data-video figure tags inserted by the Media Manager with player partials. playerPartialExists() needs the active CMS controller to resolve the theme partial (Partial::loadCached($controller->getTheme(), $name)); when Controller::getController() returns null the exception 'Media tags can only be processed for front-end requests.' is thrown. A null controller occurs whenever processHtml() runs outside an HTTP front-end request: CLI/artisan, queue workers, scheduled tasks, unit tests, or after the controller was reset mid-process.

Source

Thrown at modules/media/helpers/MediaView.php:102

        if ($this->playerPartialExists($partialName)) {
            return Controller::getController()->renderPartial($partialName, ['src' => $src]);
        }

        return $this->getDefaultPlayerMarkup($type, $src);
    }

    /**
     * playerPartialExists
     */
    protected function playerPartialExists($name)
    {
        if (array_key_exists($name, $this->playerPartialFlags)) {
            return $this->playerPartialFlags[$name];
        }

        $controller = Controller::getController();
        if (!$controller) {
            throw new ApplicationException('Media tags can only be processed for front-end requests.');
        }

        $partial = Partial::loadCached($controller->getTheme(), $name);

        return $this->playerPartialFlags[$name] = !!$partial;
    }

    /**
     * getDefaultPlayerMarkup
     */
    protected function getDefaultPlayerMarkup($type, $src)
    {
        switch ($type) {
            case 'video':
                return '<video src="'.e($src).'" controls preload="metadata"></video>';
            break;

            case 'audio':

View on GitHub (pinned to b608633a7e)

Solutions

Gate tag processing on an actual front-end controller: only call processHtml() when \Cms\Classes\Controller::getController() is non-null and not running in console
For tests, boot a CMS controller first (or mock Controller::getController()) so partial resolution has a theme context
In queue workers, generate the markup on the front-end request and persist the result, instead of re-processing raw HTML in the job

Example fix

// before — runs in a queue job / artisan command
$html = \Media\Helpers\MediaView::instance()->processHtml($page->markup);

// after — only process when a front-end controller exists
if (\Cms\Classes\Controller::getController() && !app()->runningInConsole()) {
    $html = \Media\Helpers\MediaView::instance()->processHtml($page->markup);
}

Defensive patterns

Strategy: type-guard

Type guard

function canProcessMediaTags(): bool
{
    return \Cms\Classes\Controller::getController() !== null
        && !app()->runningInConsole();
}

// usage
$html = canProcessMediaTags()
    ? \Media\Helpers\MediaView::instance()->processHtml($html)
    : $html; // leave tags untouched outside front-end requests

Try / catch

try {
    $html = \Media\Helpers\MediaView::instance()->processHtml($html);
} catch (ApplicationException $e) {
    // Queue/CLI context: fall back to raw HTML rather than failing the job
    Log::info('Skipped media tag processing: '.$e->getMessage());
}

Prevention

Keep tag post-processing on the front-end request path; persist rendered output for background consumers
Boot a CMS controller (or mock getController) in tests that render theme markup
Remember data-audio/data-video figures require a theme context — avoid them in system-generated HTML

When it happens

Trigger: Calling MediaView::instance()->processHtml($html) from a queue job or artisan command (e.g. rendering page HTML for a sitemap, PDF export, or search indexer); a PHPUnit test exercising media-tag markup without a CMS controller booted; mail/preview generation containing data-audio/data-video tags.

Common situations: Background generators that reuse front-end filters; plugin tests rendering theme content; content migrations that run tag processing in console context.

Related errors

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