What causes "Unknown flag: {arg}" in affaan-m/ECC?

Use the only supported flag, --clear, and an optional positional output directory.

affaan-m/ECC · warning · SystemExit

Unknown flag: {arg}

Error message

Unknown flag: {arg}

What it means

ws_listener.parse_args() walks sys.argv and rejects any token starting with '-' that is not the single recognized '--clear' flag. It raises SystemExit (which prints the message and exits the process) — this is a CLI usage error, not a raised exception for callers to catch.

Source

Thrown at skills/videodb/scripts/ws_listener.py:87

    """Create the listener state directory with private permissions."""
    path.mkdir(parents=True, exist_ok=True, mode=0o700)
    try:
        path.chmod(0o700)
    except OSError:
        pass
    return path


def parse_args() -> tuple[bool, Path]:
    clear = False
    output_dir: str | None = None
    
    args = sys.argv[1:]
    for arg in args:
        if arg == "--clear":
            clear = True
        elif arg.startswith("-"):
            raise SystemExit(f"Unknown flag: {arg}")
        elif not arg.startswith("-"):
            output_dir = arg
    
    if output_dir is None:
        events_dir = os.environ.get("VIDEODB_EVENTS_DIR")
        if events_dir:
            return clear, ensure_private_dir(Path(events_dir))
        return clear, ensure_private_dir(default_output_dir())

    return clear, ensure_private_dir(Path(output_dir))

CLEAR_EVENTS, OUTPUT_DIR = parse_args()
EVENTS_FILE = OUTPUT_DIR / "videodb_events.jsonl"
WS_ID_FILE = OUTPUT_DIR / "videodb_ws_id"
PID_FILE = OUTPUT_DIR / "videodb_ws_pid"

# Track if this is the first connection (for clearing events)
_first_connection = True

View on GitHub (pinned to 01e15490f0)

Solutions

Use the only supported flag, --clear, and an optional positional output directory.
Set VIDEODB_EVENTS_DIR in the environment instead of passing an output path via a flag.
Remove unsupported flags from wrapper scripts that invoke the listener.

Example fix

# before
python ws_listener.py --output /tmp/events

# after
VIDEODB_EVENTS_DIR=/tmp/events python ws_listener.py
# or, positionally:
python ws_listener.py /tmp/events

Defensive patterns

Strategy: validation

Validate before calling

import sys
SUPPORTED = {'--clear'}
def validate_argv() -> None:
    for arg in sys.argv[1:]:
        if arg.startswith('-') and arg not in SUPPORTED:
            raise SystemExit(f'Unknown flag: {arg}. Supported: --clear, plus an optional positional output dir.')

Prevention

Use VIDEODB_EVENTS_DIR to set the output directory instead of inventing flags.
Remember the parser supports only --clear and a single positional directory argument.
If you need richer CLI behavior, wrap ws_listener with argparse in a separate entrypoint.

When it happens

Trigger: Running `python ws_listener.py --port 8080`, `--help`, `-h`, `--output /tmp/x`, or any flag the minimal parser does not recognize.

Common situations: A user assumes standard flags exist (--help, --version, --output); a wrapper script passes through flags intended for a different tool; a typo such as `-clear` instead of `--clear`.

Related errors

AI-assisted analysis of affaan-m/ECC@01e15490f0 (2026-08-13). Data as JSON: /api/errors/72d5d517eeef9b52. Report an issue: GitHub.