invoke-ai/InvokeAI · error · ValueError

please provide filename for file logging using format 'file=

Error message

please provide filename for file logging using format 'file=/path/to/logfile.txt'

What it means

_parse_file_args builds a logging.FileHandler from the value of a 'file=/path/to/logfile' logging argument. If args is None or empty, there is no filename to open, so the library raises this ValueError telling you the required format. It is a guard against configuring file logging without a destination path.

Source

Thrown at invokeai/backend/util/logging.py:412

                arg_name, *arg_value = a.split(":", 2)
                if arg_name == "address":
                    host, *port_list = arg_value
                    port = 514 if not port_list else int(port_list[0])
                    syslog_args["address"] = (host, port)
                elif arg_name == "facility":
                    syslog_args["facility"] = _FACILITY_MAP[arg_value[0]]
                elif arg_name == "socktype":
                    syslog_args["socktype"] = _SOCK_MAP[arg_value[0]]
                else:
                    syslog_args["address"] = arg_name
        except Exception:
            raise ValueError(f"{args} is not a value argument list for syslog logging")
        return logging.handlers.SysLogHandler(**syslog_args)

    @staticmethod
    def _parse_file_args(args: Optional[str] = None) -> logging.Handler:  # noqa D102
        if not args:
            raise ValueError("please provide filename for file logging using format 'file=/path/to/logfile.txt'")
        return logging.FileHandler(args)

    @staticmethod
    def _parse_http_args(args: Optional[str] = None) -> logging.Handler:  # noqa D102
        if not args:
            raise ValueError("please provide destination for http logging using format 'http=url'")
        arg_list = args.split(",")
        url = urllib.parse.urlparse(arg_list.pop(0))
        if url.scheme != "http":
            raise ValueError(f"the http logging module can only log to HTTP URLs, but {url.scheme} was specified")
        host = url.hostname
        path = url.path
        port = url.port or 80

        syslog_args: Dict[str, Any] = {}
        for a in arg_list:
            arg_name, *arg_value = a.split(":", 2)
            if arg_name == "method":

View on GitHub (pinned to 0b6a024f2f)

Solutions

1. Append the log file path after 'file=' e.g. logging='file=/path/to/logfile.txt'.
2. Ensure the value isn't empty due to a shell/env variable expanding to nothing.
3. If you only wanted console logging, remove the 'file' token instead of passing it bare.

Example fix

// before
--logging file
// after
--logging file=/home/user/invokeai.log

if log_format.startswith("file"):
    path = log_format.split("=", 1)[1] if "=" in log_format else ""
    if not path:
        raise SystemExit("--logging file requires a path: file=/path/to/log.txt")

try:
    get_loggers(app, level, format="file=/var/log/invokeai.log")
except ValueError as e:
    if "provide filename for file logging" in str(e):
        log.error("Add '=path' to the file logging option")
        raise

When it happens

Trigger: Configuring logging as 'file' or 'file=' (empty value) via InvokeAI's logging config passed to get_loggers — the file handler parser receives no path.

Common situations: Setting logging='file' in invokeai.yaml or CLI --logging without appending '=path', leaving the value blank after editing a config, environment-variable interpolation producing an empty string.

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

• {args} is not a value argument list for syslog logging
• please provide destination for http logging using format 'ht
• the http logging module can only log to HTTP URLs, but {url.
• Invalid mode selected
• Unexpected control_input type: ${type(control_input)}

AI-assisted analysis of invoke-ai/InvokeAI@0b6a024f2f (2026-08-29). Data as JSON: /api/errors/51e3099c6cae8fc8. Report an issue: GitHub.