{"record":{"id":"008ece288d56ba1c","repo":"kovidgoyal/kitty","slug":"you-must-turn-on-the-dynamic-background-opacity-op","errorCode":null,"errorMessage":"You must turn on the dynamic_background_opacity option in kitty.conf to be able to set background opacity","messagePattern":"You must turn on the dynamic_background_opacity option in kitty\\.conf to be able to set background opacity","errorType":"validation","errorClass":"OpacityError","httpStatus":null,"severity":"error","filePath":"kitty/rc/set_background_opacity.py","lineNumber":76,"sourceCode":"    )\n    args = RemoteCommand.Args(spec='OPACITY', count=1, json_field='opacity', special_parse='parse_opacity(args[0])')\n\n    def message_to_kitty(self, global_opts: RCOptions, opts: 'CLIOptions', args: ArgsType) -> PayloadType:\n        opacity = max(0, min(float(args[0]), 1))\n        return {\n            'opacity': opacity,\n            'match_window': opts.match,\n            'all': opts.all,\n            'match_tab': opts.match_tab,\n            'toggle': opts.toggle,\n        }\n\n    def response_from_kitty(self, boss: Boss, window: Window | None, payload_get: PayloadGetType) -> ResponseType:\n        from kitty.fast_data_types import background_opacity_of, get_options\n\n        opts = get_options()\n        if not opts.dynamic_background_opacity:\n            raise OpacityError('You must turn on the dynamic_background_opacity option in kitty.conf to be able to set background opacity')\n        windows = self.windows_for_payload(boss, window, payload_get)\n        for os_window_id in {w.os_window_id for w in windows if w}:\n            val: float = payload_get('opacity') or 0.0\n            if payload_get('toggle'):\n                current = background_opacity_of(os_window_id)\n                # GLFW represents opacity as a float internally, but python's\n                # \"float\" type has double precision, so we can't rely on precise\n                # equality here\n                if current is not None and abs(current - val) <= 0.0001:\n                    val = opts.background_opacity\n            boss._set_os_window_background_opacity(os_window_id, val)\n        return None\n\n\nset_background_opacity = SetBackgroundOpacity()\n","sourceCodeStart":58,"sourceCodeEnd":92,"githubUrl":"https://github.com/kovidgoyal/kitty/blob/6d5d0c440603ad9bdf6dcd599f73f6dde21acb44/kitty/rc/set_background_opacity.py#L58-L92","documentation":"set-background-opacity requires the dynamic_background_opacity option to be enabled in kitty.conf because runtime opacity changes are only honored when that option is on.","triggerScenarios":"Running kitten @set-background-opacity without 'dynamic_background_opacity yes' in kitty.conf.","commonSituations":"Users adding opacity scripts (fades, dim inactive windows) without enabling the prerequisite config option.","solutions":["Add 'dynamic_background_opacity yes' to kitty.conf and restart kitty","Then re-run kitten @set-background-opacity <value>"],"exampleFix":"# kitty.conf\ndynamic_background_opacity yes","handlingStrategy":"validation","validationCode":"from kitty.config import load_config\nassert load_config().dynamic_background_opacity","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Add dynamic_background_opacity yes to kitty.conf in dotfiles/templates","Document the prerequisite in opacity scripts"],"tags":["kitty","config","opacity"],"backgroundTag":"missing-config-option","analyzedSha":"6d5d0c440603ad9bdf6dcd599f73f6dde21acb44","analyzedAt":"2026-08-27T14:20:20.142Z","schemaVersion":2},"datasetVersion":"2026-08-27T19:17:21.184Z"}