AUTOMATIC1111/stable-diffusion-webui · warning · RuntimeError

not possible to set '{key}' because it is restricted

Error message

not possible to set '{key}' because it is restricted

What it means

Options.__setattr__ performs several guards before allowing a settings change; this RuntimeError fires when the setting's component_args is a dict with visible=False, i.e. the setting is deliberately hidden/restricted in the UI (not meant to be set programmatically). It is a policy check, not a data problem.

Source

Thrown at modules/options.py:108

    def __setattr__(self, key, value):
        if key in options_builtin_fields:
            return super(Options, self).__setattr__(key, value)

        if self.data is not None:
            if key in self.data or key in self.data_labels:

                # Check that settings aren't globally frozen
                assert not cmd_opts.freeze_settings, "changing settings is disabled"

                # Get the info related to the setting being changed
                info = self.data_labels.get(key, None)
                if info.do_not_save:
                    return

                # Restrict component arguments
                comp_args = info.component_args if info else None
                if isinstance(comp_args, dict) and comp_args.get('visible', True) is False:
                    raise RuntimeError(f"not possible to set '{key}' because it is restricted")

                # Check that this section isn't frozen
                if cmd_opts.freeze_settings_in_sections is not None:
                    frozen_sections = list(map(str.strip, cmd_opts.freeze_settings_in_sections.split(','))) # Trim whitespace from section names
                    section_key = info.section[0]
                    section_name = info.section[1]
                    assert section_key not in frozen_sections, f"not possible to set '{key}' because settings in section '{section_name}' ({section_key}) are frozen with --freeze-settings-in-sections"

                # Check that this section of the settings isn't frozen
                if cmd_opts.freeze_specific_settings is not None:
                    frozen_keys = list(map(str.strip, cmd_opts.freeze_specific_settings.split(','))) # Trim whitespace from setting keys
                    assert key not in frozen_keys, f"not possible to set '{key}' because this setting is frozen with --freeze-specific-settings"

                # Check shorthand option which disables editing options in "saving-paths"
                if cmd_opts.hide_ui_dir_config and key in self.restricted_opts:
                    raise RuntimeError(f"not possible to set '{key}' because it is restricted with --hide_ui_dir_config")

                self.data[key] = value

View on GitHub (pinned to 82a973c043)

Solutions

  1. Do not set the restricted key from code; choose the user-facing setting that governs the behavior instead.
  2. If you own the setting definition, remove 'visible': False from its component_args when registering it if programmatic writes should be allowed.
  3. Check whether the value you need is better passed as a command-line argument at launch instead of a runtime option write.

Example fix

# before
shared.opts.set('some_hidden_key', 'value')  # RuntimeError: restricted

# after
# use the public setting or configure at launch
shared.opts.set('sd_model_checkpoint', 'model.safetensors')  # non-restricted key
Defensive patterns

Strategy: validation

Validate before calling

def can_set_option(opts, key):
    info = opts.data_labels.get(key)
    if info is None:
        return True
    comp = info.component_args if isinstance(info.component_args, dict) else None
    return not (comp and comp.get('visible', True) is False)

if can_set_option(shared.opts, key):
    shared.opts.set(key, value)

Type guard

def is_settable_option(key: str) -> bool:
    info = shared.opts.data_labels.get(key)
    if info is None:
        return True
    comp = info.component_args if isinstance(info.component_args, dict) else None
    return not (comp and comp.get('visible', True) is False)

Try / catch

try:
    shared.opts.set(key, value)
except RuntimeError as e:
    if 'restricted' in str(e):
        pass  # policy denies this key; not retryable
    else:
        raise

Prevention

When it happens

Trigger: Calling shared.opts.set('key', value) or assigning opts.<key> where the OptionInfo for that key declares component_args={'visible': False}; also triggered via the settings API endpoint for such restricted keys.

Common situations: Extensions or scripts trying to programmatically change an internal/hidden setting; using the /sdapi/v1/options API to write a key the UI deliberately hides in this build.

Related errors

AI-assisted analysis of AUTOMATIC1111/stable-diffusion-webui@82a973c043 (2026-08-14). Data as JSON: /api/errors/ecea68fe8518a8c7. Report an issue: GitHub.