What causes "cms::lang.cms_object.file_name_required" in octobercms/october?

Always set a non-empty file name before save (e.g. 'en.json').

octobercms/october · warning · ValidationException

cms::lang.cms_object.file_name_required

Error message

cms::lang.cms_object.file_name_required

What it means

ValidationException thrown by `Lang::validateFileName()` (called from save() and delete()) when the trimmed file name is an empty string. The message also lists the allowed extensions (json) so the user knows the expected format. This fires before any disk operation, so nothing is written or removed.

Source

Thrown at modules/cms/classes/Lang.php:335

                    ['name' => $this->fileName]
                ));
            }
        }
    }

    /**
     * validateFileName supplied with extension and path.
     */
    protected function validateFileName($fileName = null)
    {
        if ($fileName === null) {
            $fileName = $this->fileName;
        }

        $fileName = trim($fileName);

        if (!strlen($fileName)) {
            throw new ValidationException(['fileName' =>
                LangHelper::get('cms::lang.cms_object.file_name_required', [
                    'allowed' => implode(', ', $this->allowedExtensions),
                    'invalid' => pathinfo($fileName, PATHINFO_EXTENSION)
                ])
            ]);
        }

        if (!FileHelper::validateExtension($fileName, $this->allowedExtensions, false)) {
            throw new ValidationException(['fileName' =>
                LangHelper::get('cms::lang.cms_object.invalid_file_extension', [
                    'allowed' => implode(', ', $this->allowedExtensions),
                    'invalid' => pathinfo($fileName, PATHINFO_EXTENSION)
                ])
            ]);
        }

        if (!FileHelper::validatePath($fileName, null)) {
            throw new ValidationException(['fileName' =>

View on GitHub (pinned to b608633a7e)

Solutions

Always set a non-empty file name before save (e.g. 'en.json').
Add required validation on the client/form side so blank names never reach the API.
Default the name programmatically when creating: `$lang->fileName = $lang->fileName ?: 'en.json';`.

Example fix

// before
$lang->fill(['fileName' => '   ', 'content' => '{}']);
$lang->save(); // throws file_name_required

// after
$lang->fill(['fileName' => 'en.json', 'content' => '{}']);
$lang->save();

Defensive patterns

Strategy: validation

Validate before calling

$name = trim((string) $request->input('fileName', ''));
if ($name === '') {
    throw new ValidationException(['fileName' => 'File name is required.']);
}
$lang->fileName = $name;
$lang->save();

Try / catch

try {
    $lang->save();
} catch (Winter\Storm\Exception\ValidationException $e) {
    return back()->withErrors($e->getErrors())->withInput();
}

Prevention

Make the file-name field required in your form validation rules before submission.
Default new lang objects to a sensible name ('en.json') when creating them programmatically.
Trim and reject whitespace-only input at the boundary.

When it happens

Trigger: Saving a Lang object that was never given a fileName (e.g. `new Lang` + fill(['content' => ...]) then save()); a form/AJAX request submitting a blank file name field; whitespace-only file name from an import.

Common situations: Front-end forms missing a required-field check before posting to the CMS API; import scripts with empty rows; programmatic creation that assumes a default name exists.

Related errors

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