flarum/framework · error · RuntimeException

Cannot modify immutable default setting $key.

Error message

Cannot modify immutable default setting $key.

What it means

Flarum's Extend\Settings::extend() merges extension-provided default settings into the container's flarum.settings.default collection. If an extension tries to set a default for a key that already has a default (from core or another extension), it throws this RuntimeException, because defaults are immutable — extensions may only add new default keys, not override existing ones.

Solutions

1. Change the extension to use a unique settings key (prefixed with the extension id) instead of reusing the existing one.
2. Remove the ->default() call for keys owned by core/other extensions; read the existing value at runtime instead of trying to override it.
3. If overriding is truly needed, do it after boot by writing the setting to the DB (settings table) rather than via the defaults container extension.
4. Identify the conflicting extension by checking which other extension registers the same default key.

Example fix

// before
(new Extend\Settings())->default('flarum-tags.min_primary_tags', 1)
// after
(new Extend\Settings())->default('my-extension.min_primary_tags', 1) // unique, non-conflicting key

// ensure your default keys are namespaced and not core keys
foreach ($myDefaults as $key => $value) {
    if (str_starts_with($key, 'flarum-') && ! str_starts_with($key, 'flarum-my-extension-')) {
        throw new \LogicException("Do not override core default: $key");
    }
}

try {
    (new Extend\Settings())->default($key, $value)->extend($container, $extension);
} catch (\RuntimeException $e) {
    // log conflicting key and skip or rename it
}

When it happens

Trigger: An extension calling (new Extend\Settings())->default('existing_key', $value) where 'existing_key' was already defaulted by Flarum core or a previously-loaded extension, executed during the container extend phase of boot.

Common situations: Two extensions both defining a default for the same setting key; an extension trying to override a core default to change behavior; upgrading Flarum where a key that used to be unclaimed now has a core default, breaking a previously working extension.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

• Last update runs can only be for one of: minor, major…

AI-assisted analysis of flarum/framework@4b939f6853 (2026-09-15). Data as JSON: /api/errors/8052c94d25e1d2fe. Report an issue: GitHub.

Appendix: source

Thrown at framework/core/src/Extend/Settings.php:117

    /**
     * Register a setting that should trigger JS cache clear when saved.
     *
     * @param string $setting: The key of the setting.
     */
    public function resetJsCacheFor(string $setting): self
    {
        $this->resetJsCacheFor[] = $setting;

        return $this;
    }

    public function extend(Container $container, ?Extension $extension = null): void
    {
        if (! empty($this->defaults)) {
            $container->extend('flarum.settings.default', function (Collection $defaults) {
                foreach ($this->defaults as $key => $value) {
                    if ($defaults->has($key)) {
                        throw new \RuntimeException("Cannot modify immutable default setting $key.");
                    }

                    $defaults->put($key, $value);
                }

                return $defaults;
            });
        }

        if (! empty($this->resetWhen)) {
            foreach ($this->resetWhen as $key => $callback) {
                Arr::set(
                    SetSettingsController::$resetWhen,
                    $key,
                    ContainerUtil::wrapCallback($callback, $container)
                );
            }
        }

View on GitHub (pinned to 4b939f6853)