zaproxy/zaproxy · error · ApiException

MODE_VIOLATION

MODE_VIOLATION

Error message

MODE_VIOLATION

What it means

In ZAP 'safe' mode all potentially destructive operations are blocked. scanURL checks Control.getSingleton().getMode() before starting an active scan and unconditionally throws ApiException(MODE_VIOLATION) in safe mode.

Source

Thrown at zap/src/main/java/org/zaproxy/zap/extension/ascan/ActiveScanAPI.java:941

            }

            if (node == null) {
                throw new ApiException(ApiException.Type.URL_NOT_FOUND);
            }
        }
        Target target;
        if (useUrl) {
            target = new Target(node);
            target.setContext(context);
        } else {
            target = new Target(context);
        }
        target.setRecurse(scanChildren);
        target.setInScopeOnly(scanJustInScope);

        switch (Control.getSingleton().getMode()) {
            case safe:
                throw new ApiException(ApiException.Type.MODE_VIOLATION);
            case protect:
                if ((useUrl && !Model.getSingleton().getSession().isInScope(url))
                        || (context != null && !context.isInScope())) {
                    throw new ApiException(ApiException.Type.MODE_VIOLATION);
                }
                // No problem
                break;
            case standard:
                // No problem
                break;
            case attack:
                // No problem
                break;
        }

        Object[] objs = new Object[] {};
        if (policy != null) {
            objs = new Object[] {policy};

View on GitHub (pinned to 9d1970a436)

Solutions

1. Switch ZAP to 'standard', 'protect', or 'attack' mode first via core/setMode or the UI mode dropdown.
2. In CI, start ZAP in a mode suitable for scanning (e.g. -config api.mode or set core/setMode=standard at startup).
3. Guard your pipeline: read the current mode with core/mode and fail fast with a clear message before attempting scans.

Example fix

// before
zap.scan.scan(url: target); // mode = SAFE
// after
zap.core.setMode("standard");
zap.scan.scan(url: target);

const mode = await api.core.mode();
if (mode === 'safe') throw new Error('Active scan blocked: ZAP is in SAFE mode');

function scanAllowed(mode) { return mode === 'standard' || mode === 'protect' || mode === 'attack'; }

try { api.scan(url); } catch (e) { if (String(e).includes('MODE_VIOLATION')) { await api.core.setMode('standard'); return api.scan(url); } throw e; }

When it happens

Trigger: Calling ascan/scan (or scanAsUser) while ZAP's mode is set to SAFE (UI mode selector or API/core setMode), regardless of the URL or parameters.

Common situations: CI runners using a safe-mode profile for protection; mode left at safe after a policy-restricted setup; user switched modes in the desktop UI while automation runs.

Related errors

• SCRIPT_NOT_FOUND
• USER_NOT_FOUND
• DISABLED
• MISSING_PARAMETER
• INTERNAL_ERROR

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