BookStackApp/BookStack · error · ThemeModuleException

Module in folder "{$folderName}" is missing a valid 'descrip

Error message

Module in folder "{$folderName}" is missing a valid 'description' property

What it means

ThemeModuleException guard in ThemeModule::fromJson rejecting a bookstack-module.json manifest whose 'description' value is absent or not a string. Input at fault: the module's JSON manifest with an invalid description field.

Source

Thrown at app/Theming/ThemeModule.php:27

        public string $description,
        public string $version,
        public string $folderName,
    ) {
    }

    /**
     * Create a ThemeModule instance from JSON data.
     *
     * @throws ThemeModuleException
     */
    public static function fromJson(array $data, string $folderName): self
    {
        if (empty($data['name']) || !is_string($data['name'])) {
            throw new ThemeModuleException("Module in folder \"{$folderName}\" is missing a valid 'name' property");
        }

        if (!isset($data['description']) || !is_string($data['description'])) {
            throw new ThemeModuleException("Module in folder \"{$folderName}\" is missing a valid 'description' property");
        }

        if (!isset($data['version']) || !is_string($data['version'])) {
            throw new ThemeModuleException("Module in folder \"{$folderName}\" is missing a valid 'version' property");
        }

        if (!preg_match('/^v?\d+\.\d+\.\d+(-.*)?$/', $data['version'])) {
            throw new ThemeModuleException("Module in folder \"{$folderName}\" has an invalid 'version' format. Expected semantic version format like '1.0.0' or 'v1.0.0'");
        }

        return new self(
            name: $data['name'],
            description: $data['description'],
            version: $data['version'],
            folderName: $folderName,
        );
    }

View on GitHub (pinned to 18f8469a1c)

Solutions

Add a string 'description' field to the module descriptor in the folder named in the message
Ensure the value is a plain string, not a nested object/array or number
Update the module to a version compatible with your BookStack release
Validate the descriptor JSON parses correctly (syntax errors can drop keys)

Example fix

// before
{ "name": "my-module" }
// after
{ "name": "my-module", "description": "Adds a custom footer to pages" }

Defensive patterns

Strategy: validation

Validate before calling

function validateDescription(array $data, string $folder): void {
    if (!isset($data['description']) || !is_string($data['description'])) {
        throw new InvalidArgumentException("Module in folder \"{$folder}\" needs a string 'description'");
    }
}

Type guard

function hasValidDescription(array $data): bool {
    return isset($data['description']) && is_string($data['description']);
}

Try / catch

try {
    $module = ThemeModule::fromJson($data, $folderName);
} catch (ThemeModuleException $e) {
    if (str_contains($e->getMessage(), "'description'")) {
        // show author which property to add
    }
}

Prevention

Always add a human-readable 'description' string to module descriptors
Start from the official module template/starter
Run a schema check (name, description, version as strings) in CI before packaging
Avoid programmatic generation that can emit null for optional-looking fields

When it happens

Trigger: fromJson (invoked by loadFromFolder/getModuleInstance) receives $data with 'name' valid but 'description' missing, null, or a non-string (e.g. a number or array).

Common situations: Minimal module descriptors that only include a name; templates from old BookStack versions before description became required; copy-pasted descriptors with the key removed or renamed.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

AI-assisted analysis of BookStackApp/BookStack@18f8469a1c (2026-09-02). Data as JSON: /api/errors/904a092790b1dcbc. Report an issue: GitHub.