What causes "start.gui.cmdline.session.path.invalid" in zaproxy/zaproxy?

Verify the -session argument points to an existing ZAP session file with the correct extension and location.

start.gui.cmdline.session.path.invalid

Error message

start.gui.cmdline.session.path.invalid

What it means

Raised in GuiBootstrap.run when the -session command-line argument cannot be resolved to a valid session path. SessionUtils.getSessionPath throws IllegalArgumentException for invalid paths; the code logs a warning and, seeing a null sessionPath, shows a warning dialog with this i18n message and aborts opening the session in the GUI.

Source

Thrown at zap/src/main/java/org/zaproxy/zap/GuiBootstrap.java:258

                        view.getMainFrame().setVisible(true);

                        boolean createNewSession = true;
                        if (getArgs().isEnabled(CommandLine.SESSION)
                                && getArgs().isEnabled(CommandLine.NEW_SESSION)) {
                            view.showWarningDialog(
                                    Constant.messages.getString(
                                            "start.gui.cmdline.invalid.session.options",
                                            CommandLine.SESSION,
                                            CommandLine.NEW_SESSION,
                                            Constant.getZapHome()));

                        } else if (getArgs().isEnabled(CommandLine.SESSION)) {
                            String path = getArgs().getArgument(CommandLine.SESSION);
                            Path sessionPath = null;
                            try {
                                sessionPath = SessionUtils.getSessionPath(path);
                            } catch (IllegalArgumentException e) {
                                LOGGER.warn(
                                        "An error occurred while resolving the session path:", e);
                            }

                            if (sessionPath == null) {
                                view.showWarningDialog(
                                        Constant.messages.getString(
                                                "start.gui.cmdline.session.path.invalid", path));
                            } else if (!Files.exists(sessionPath)) {
                                view.showWarningDialog(
                                        Constant.messages.getString(
                                                "start.gui.cmdline.session.does.not.exist",
                                                Constant.getZapHome()));

                            } else {
                                createNewSession =
                                        !control.getMenuFileControl()
                                                .openSession(
                                                        sessionPath.toAbsolutePath().toString());

View on GitHub (pinned to 9d1970a436)

Solutions

Verify the -session argument points to an existing ZAP session file with the correct extension and location.
Use an absolute path or a path consistent with the configured sessions directory.
List the sessions directory to find the correct session name, or omit -session and pick the session in the GUI.
Check the ZAP log for the 'An error occurred while resolving the session path' warning to see the underlying IllegalArgumentException.

Example fix

// before
zap.sh -session /nonexistent/mysession

// after
zap.sh -session /home/user/ZAP/sessions/mysession.session

Defensive patterns

Strategy: validation

Validate before calling

Path p = Paths.get(sessionArg);
boolean valid = Files.isRegularFile(p) && p.toString().endsWith(".session");
if (!valid) { System.err.println("Invalid -session path: " + sessionArg); }

Try / catch

try { Path sp = SessionUtils.getSessionPath(path); } catch (IllegalArgumentException e) { LOGGER.warn("Invalid session path", e); view.showWarningDialog(msg); }

Prevention

Pass an absolute path to an existing .session file
Confirm the session file exists before launching with -session
Keep session files in the configured sessions directory
Check ZAP startup logs for path-resolution warnings

When it happens

Trigger: Starting ZAP GUI with -session <path> where the path is not a valid session path (nonexistent file, missing/incorrect .session extension, or path not under the sessions directory as enforced by SessionUtils.getSessionPath).

Common situations: Typos in the session path on the command line; passing a session name without the expected extension or directory; moving/deleting session files between runs; relative vs absolute path confusion.

Related errors

AI-assisted analysis of zaproxy/zaproxy@9d1970a436 (2026-09-05). Data as JSON: /api/errors/9ca65d6d1d10c47d. Report an issue: GitHub.