zaproxy/zaproxy · error · ApiException

ILLEGAL_PARAMETER

ILLEGAL_PARAMETER

Error message

ILLEGAL_PARAMETER: e.getMessage()

What it means

ProxiesAPI.handleApiAction wraps any exception from extension.addProxy into ApiException(ILLEGAL_PARAMETER) carrying the underlying message. So 'proxy already exists' or 'cannot listen on' failures during the addProxy API action surface as ILLEGAL_PARAMETER.

Source

Thrown at zap/src/main/java/org/zaproxy/zap/extension/proxies/ProxiesAPI.java:111

        }
    }

    @Override
    public ApiResponse handleApiAction(String name, JSONObject params) throws ApiException {
        if (ACTION_ADD_PROXY.equals(name)) {
            try {
                extension.addProxy(
                        new ProxiesParamProxy(
                                params.getString(PARAM_ADDRESS),
                                params.getInt(PARAM_PORT),
                                true,
                                false,
                                this.getParam(params, PARAM_REM_UNSUPPORTED_ENC, false),
                                this.getParam(params, PARAM_DECODE_ZIP, false),
                                this.getParam(params, PARAM_BEHIND_NAT, false)));
                return ApiResponseElement.OK;
            } catch (Exception e) {
                throw new ApiException(ApiException.Type.ILLEGAL_PARAMETER, e.getMessage());
            }
        } else if (ACTION_REMOVE_PROXY.equals(name)) {
            try {
                extension.removeProxy(params.getString(PARAM_ADDRESS), params.getInt(PARAM_PORT));
                return ApiResponseElement.OK;
            } catch (Exception e) {
                throw new ApiException(ApiException.Type.ILLEGAL_PARAMETER, e.getMessage());
            }
        } else {
            throw new ApiException(ApiException.Type.BAD_VIEW, name);
        }
    }
}

View on GitHub (pinned to 9d1970a436)

Solutions

  1. Read e.getMessage() in the error detail to see whether it's 'Proxy already exists' or 'Cannot listen on' and act accordingly.
  2. Check existing proxies via /JSON/proxies/view/additionalProxies/ before adding.
  3. Ensure 'port' is sent as a valid integer and the address is a local interface.
  4. Pick a free port and deduplicate add calls in setup scripts.

Example fix

// before
curl "http://zap:8080/JSON/proxies/action/addProxy/?port=8080" // missing address -> ILLEGAL_PARAMETER
// after
curl "http://zap:8080/JSON/proxies/action/addProxy/?address=127.0.0.1&port=8091"
Defensive patterns

Strategy: try-catch

Validate before calling

boolean duplicate = getAdditionalProxy(address, port) != null;
boolean bindable = canListenOn(address, port);
if (duplicate || !bindable || !port.matches("\\d+")) {
    // fix inputs before calling /JSON/proxies/action/addProxy/
}

Try / catch

try {
    api.call("/JSON/proxies/action/addProxy/?address=..&port=..");
} catch (ApiException e) {
    if (e.getType() == ApiException.Type.ILLEGAL_PARAMETER) {
        String detail = e.getMessage(); // 'Proxy already exists' vs 'Cannot listen on'
    }
}

Prevention

When it happens

Trigger: Calling proxies/action/addProxy/ where the address:port duplicates an existing proxy or cannot be bound (port occupied, invalid local address, privileged port), or with malformed 'port' that fails integer parsing.

Common situations: Automation re-adding an existing listener; port conflicts with other services; wrong type for port param (e.g. '8080x'); binding to a hostname that doesn't resolve to a local interface.

Related errors

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