What causes "conn.options.proxy.username.empty" in zaproxy/zaproxy?

Enter the upstream proxy username in the authentication section

zaproxy/zaproxy · warning · Exception

conn.options.proxy.username.empty

Error message

conn.options.proxy.username.empty

What it means

validateParam() in OptionsConnectionPanel also validates proxy-chain authentication fields. When proxy chain authentication is enabled and 'Prompt on authentication failure' is not selected, the proxy username must not be empty; otherwise a generic Exception with the i18n key conn.options.proxy.username.empty is thrown and the username field receives focus.

Source

Thrown at zap/src/main/java/org/parosproxy/paros/extension/option/OptionsConnectionPanel.java:662

        chkShowPassword.setEnabled(!isEnabled);
    }

    @Override
    public void validateParam(Object obj) throws Exception {

        if (chkUseProxyChain.isSelected()) {
            // ZAP: empty proxy name validation
            if (txtProxyChainName.getText().isEmpty()) {
                txtProxyChainName.requestFocus();
                throw new Exception(
                        Constant.messages.getString("conn.options.proxy.address.empty"));
            }

            if (chkProxyChainAuth.isSelected()
                    && !chkProxyChainPrompt.isSelected()
                    && txtProxyChainUserName.getText().isEmpty()) {
                txtProxyChainUserName.requestFocus();
                throw new Exception(
                        Constant.messages.getString("conn.options.proxy.username.empty"));
            }
        }

        securityProtocolsPanel.validateSecurityProtocols();

        socksProxyPanel.validateParam();
    }

    @Override
    public void saveParam(Object obj) throws Exception {

        OptionsParam optionsParam = (OptionsParam) obj;
        org.parosproxy.paros.network.ConnectionParam connectionParam =
                optionsParam.getConnectionParam();

        connectionParam.setProxyChainName(txtProxyChainName.getText());
        // ZAP: Do not allow invalid port numbers

View on GitHub (pinned to 9d1970a436)

Solutions

Enter the upstream proxy username in the authentication section
Tick 'Prompt on authentication failure' to supply credentials interactively instead
Disable 'Proxy chain authentication' if the upstream proxy needs no auth

Example fix

// before
chkProxyChainAuth.setSelected(true); // empty username -> 'conn.options.proxy.username.empty'
// after
chkProxyChainAuth.setSelected(true);
txtProxyChainUserName.setText("proxyuser");
txtProxyChainPassword.setText("secret");

Defensive patterns

Strategy: validation

Validate before calling

if (useProxyChain && chainAuth && !promptForCreds && (username == null || username.isEmpty())) {
    // require username (or enable 'Prompt on authentication failure') before saving
}

Try / catch

try {
    optionsPanel.validateParam(connectionOptions);
} catch (Exception e) {
    if ("conn.options.proxy.username.empty".equals(e.getMessage())) {
        focusUsernameField();
    }
}

Prevention

When enabling proxy-chain auth, immediately supply username/password
Use 'Prompt on authentication failure' when credentials are unknown at config time
Validate dependent fields together (checkbox + auth + credentials)
Keep proxy credentials in a config source, not empty placeholders

When it happens

Trigger: Options > Connection with 'Use proxy chain' + 'Proxy chain authentication' checked, 'Prompt...' unchecked, and the Username field left blank when saving.

Common situations: Enabling authenticated upstream proxy but forgetting credentials; clearing the username while keeping auth enabled; headless/config-file setups that toggle auth without setting the username.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

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