octobercms/october · error · SystemException

Invalid documentMetadata

Error message

Invalid documentMetadata

What it means

getRequestMetadata() reads `documentMetadata` from the current request and requires an array. Editor extension commands (e.g. save) depend on it — mtime, path, type — to detect concurrent-edit conflicts. Missing, string, or null input throws SystemException('Invalid documentMetadata').

Source

Thrown at modules/tailor/classes/editorextension/HasExtensionCrud.php:287

        $result = [
            'mtime' => $template->mtime,
            'path' => $fileName,
            'type' => $documentType,
            'typeName' => $typeNames[$documentType]
        ];

        return $result;
    }

    /**
     * getRequestMetadata
     */
    private function getRequestMetadata()
    {
        $metadata = Request::input('documentMetadata');
        if (!is_array($metadata)) {
            throw new SystemException('Invalid documentMetadata');
        }

        return $metadata;
    }

    /**
     * getRequestExtraData
     */
    private function getRequestExtraData()
    {
        $extraData = Request::input('extraData');
        if (!is_array($extraData)) {
            return [];
        }

        return $extraData;
    }

View on GitHub (pinned to b608633a7e)

Solutions

1. Include documentMetadata as an array mirroring what onOpenDocument returned (path, type, mtime at minimum).
2. In custom clients, echo back the exact metadata object the editor provided on open.
3. After upgrades, clear cached editor assets so the shipped client payload is used.

$metadata = \Request::input('documentMetadata');
if (!is_array($metadata) || !isset($metadata['path'], $metadata['type'])) {
    throw new InvalidArgumentException('documentMetadata array with path and type is required.');
}

function isValidDocumentMetadata($metadata): bool
{
    return is_array($metadata) && isset($metadata['path'], $metadata['type']);
}

try {
    $metadata = $this->getRequestMetadata();
} catch (\SystemException $e) {
    // request malformed — respond 422 and have the client re-open the document to obtain metadata
}

When it happens

Trigger: Invoking an editor extension AJAX command that calls getRequestMetadata() without supplying documentMetadata, or sending it serialized as a JSON string rather than an array of form values.

Common situations: Custom editor integrations that don't round-trip the metadata returned by onOpenDocument; automated tests hitting handlers directly; payload shape drift after CMS upgrades.

Related errors

• Document data is not provided
• Invalid documentData
• Custom widget class [{$widgetClass}] is not set.
• The property name is not specified.
• Custom widget class [{$widgetClass}] is not set.

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