errors.md

# Error messages

When sipnab refuses to start a run, or stops part way through one, it prints a
message. The message says why.

- This page lists those messages, so that you can look one up by its text.
- Search this page for a distinctive part of the message you see. For example,
  search for a flag name or the first few words.

## How to read an entry

Each heading is a message exactly as sipnab's source code writes it.

- A name in braces, such as `{path}`, is a placeholder. sipnab puts a value
  there when it prints the message, such as a file name.
- A pair of empty braces, `{}`, is a placeholder without a name.
- `\n` marks a line break.

Under each heading:

- the first paragraph says what the message means, and what the placeholders
  hold;
- **What to do** says how to get past it;
- **Exit code** is the number sipnab returns to the shell when the message
  stops the run.
  - [Exit codes](cli-reference.md#exit-codes) in the CLI reference explains
    each code.
  - An entry marked as a warning does not stop the run.

sipnab prints most messages as log lines on stderr, in this form. stderr is
the standard error stream. A shell shows it on the terminal unless you
redirect it.

```text
2026-10-12T04:04:45.184315Z ERROR sipnab::app::bootstrap: config file not found: /nonexistent/x.toml
```

- The part after the module name (`sipnab::app::bootstrap:`) is the message.
- `ERROR` lines are errors and `WARN` lines are warnings.
- In the terminal UI, sipnab shows only `ERROR` lines, unless the `SIPNAB_LOG`
  environment variable sets a level. To see the warnings as well, do one of
  these:
  - run with `-N` (no terminal UI);
  - set `SIPNAB_LOG=info`.
- sipnab writes a few messages to stderr without the timestamp and level.
  These messages decide the exit code, so they must appear even when logging
  is off. sipnab refuses a flag that needs a feature this build does not
  include in this way, for example
  `--tls-key requires the 'tls' feature (not compiled in)`.

## What this page covers

The page lists the messages that the startup and exit path of the `sipnab`
command raises:

- argument checks;
- the configuration file;
- the run planner, which turns flags and the configuration into a run;
- the run modes (batch, terminal UI, the listeners, vCon export, fetch and
  forwarding).

It also lists the warnings that these parts of sipnab print while the run
continues.

The page does not list:

- the error bodies the REST API returns, which [REST API](rest-api.md)
  documents;
- the errors the MCP server returns to an agent, which
  [MCP protocol](mcp-protocol.md) documents;
- errors from the WebAssembly build of the library;
- the text of errors that come from deeper inside sipnab or from the
  operating system. For example, from the capture code, or from a file sipnab
  cannot open.
  - Startup messages often end with such a text after a colon.
  - The entry for the startup message explains the part before the colon.

A test,
[`tests/error_reference_test.rs`](https://github.com/NormB/sipnab/blob/main/tests/error_reference_test.rs),
reads the messages in the source code. It fails in two cases:

- a message has no entry here;
- an entry names a message that sipnab no longer prints.

## Command-line flags

### `--alert exec given without --alert-exec <CMD>; no command to run`

You gave `--alert exec`, but no `--alert-exec <CMD>` (or `[security] alert_exec`) names the command to run, so the `exec` alert channel does nothing.

**What to do:** Add `--alert-exec <CMD>`, or remove `exec` from `--alert`.

**Exit code:** None. This is a warning, and the run continues.

### `autostop {key} must be > 0, got 0 (0 stops the capture immediately)`

The number in `--autostop` is 0. `{key}` is the condition (`duration`, `filesize` or the unknown name given). A zero limit would stop the capture immediately. Printed after the prefix `Invalid --autostop: `.

**What to do:** Give a number above 0, for example `--autostop duration:60`.

**Exit code:** 2.

### `both --input/-I and --device/-d given: reading the FILE and ignoring the interface. Drop -I to capture live traffic.`

A warning: the command line has both `-I` (read a capture file) and `-d` (capture from an interface). sipnab reads the file and does not open the interface.

**What to do:** Remove `-I` to capture live traffic. Or remove `-d` to silence the warning when you mean to read the file.

**Exit code:** None. This is a warning, and the run continues.

### `--business-hours {reason}`

The value given to `--business-hours` is not a usable working-hours window. `{reason}` says why. There are two cases:

- The value is not two whole hours from 0 to 23 joined by `-`. The reason then quotes the value.
- The start and end hours are equal. That would be a zero-length window, which treats every call as off-hours.

**What to do:** Give `--business-hours` as `START-END`, in whole hours 0-23, with different start and end.

- For example, `8-18`.
- Or `22-6` for a window that crosses midnight.

**Exit code:** 2.

### `cannot read suppression file '{name}': {e}`

You gave `--lint` with a suppression file (`{name}`, from `--lint-suppress-file`), and sipnab could not read it. The text after the colon is the reason.

**What to do:** Check the path and its read permission, or pass `--lint-no-suppress` to lint without suppressions.

**Exit code:** 2.

### `cannot read the discovered .sipnablint: {e}`

`--lint` found a `.sipnablint` file beside the first `-I` input (or in the `-I` directory) and could not read or parse it. The text after the colon is the reason.

**What to do:** Fix or remove that `.sipnablint` file, name a different one with `--lint-suppress-file`, or pass `--lint-no-suppress`.

**Exit code:** 2.

### `--capture-tunnels was given an empty port list; drop the flag, or pass ports, e.g. --capture-tunnels={TUNNEL_PORTS_DEFAULT_LIST}`

`--capture-tunnels` takes a comma-separated list of UDP ports. The generated capture filter takes the traffic on these ports in full. It is for tunnels such as GTP-U or VXLAN.

- `{TUNNEL_PORTS_DEFAULT_LIST}` is the default list, `2152,4789,6081`.
- sipnab checks each port before it reaches this check.
- An empty value fails that earlier check first. So a run prints the `Invalid --capture-tunnels port` message instead of this one.

**What to do:** Follow the entry for `Invalid --capture-tunnels port '{text}'`: pass one or more ports, for example `--capture-tunnels=2152,4789`, or remove the flag.

**Exit code:** 2.

### `cn-suppression-ratio is a share of the packets and must be a finite number > 0 and <= 1, got {v}`

`--cn-suppression-ratio` takes a share of a stream's packets: a finite number greater than 0 and at most 1. `{v}` is the number as read. The value lies outside that range, or is `nan` or infinite.

**What to do:** Give a number greater than 0 and no greater than 1, for example `0.5`.

**Exit code:** 2.

### `--cores {} does not do what {} asks for: the parallel reader rebuilds dialogs per shard and prints only whole-capture views, so it would skip them and still exit 0. Drop --cores for these, or keep --cores and ask for a whole-capture view instead (--json-dialogs, --report, --analyze, --call-report).`

`--cores` above 1 with `-I` (and without `--multi-device`) uses the parallel file reader. It prints the whole-capture views and nothing per message.

- The first placeholder is the `--cores` value.
- The second lists the flags on the command line, or the keys in the config file, that the parallel reader does not carry out:
  - output: `--json`/`--json-pretty`, `--text-dump`, `--fail2ban`, `-O/--output`, `--hexdump`, `--group-by`, `--wireshark`, `--tshark-filter`, `--recommend-block`, `--evidence-out`;
  - matching: `--match`, `--from`, `--to`, `--contact`, `--ua`, `--tag`;
  - DTMF and hooks: `--telephone-event`, `--on-dialog-exec`, `--on-quality-exec`;
  - transmission and servers: `--hep-send`, `--api`, `--mcp`, `--relay-compare`, `--allow-action`, `--syslog`;
  - decryption: `--srtp-keys`, `--dtls-keylog`, `--keylog` (and `--keylog-fd`, `--keylog-watch`), `--tls-key`;
  - `--replay`;
  - confinement: `--sandbox`, `--seccomp`, and `--chroot` whether set by the flag or by `[privilege]`.
- sipnab refuses rather than skip them and exit 0.

**What to do:** Do one of these:

- Remove `--cores` (or set it to 1) to keep those flags.
- Keep `--cores` and drop them, asking for `--json-dialogs`, `--report`, `--analyze` or `--call-report` instead.

**Exit code:** 2.

### `--cores {} asks for no view: the parallel reader prints no per-message lines, so this run would read the capture, print nothing and still exit 0. Ask for a whole-capture view (--report, --json-dialogs, --analyze, --call-report), or drop --cores for per-message output.`

`--cores` above 1 with `-I` (and without `--multi-device`) uses the parallel file reader, which prints only the whole-capture views you ask for. The command line asks for none of them, and the config file holds no `[[vcon.rule]]`. The placeholder is the `--cores` value. sipnab refuses before reading the capture.

**What to do:** Do one of these:

- Add a view, for example `sipnab -N -I capture.pcap --cores 4 --report`. The views are `--report`, `--json-dialogs`, `--stun`, `--json-stun`, `--analyze`, `--json-analyze`, `--yang-analyze`, `--call-report`, `--export-vcon`, `--export-vcon-when` and `--lint`.
- Remove `--cores` (or set it to 1) to print one line per SIP message.

**Exit code:** 2.

### `--cores opens all {files} input file(s) before dropping root privileges, and this process may hold {soft_limit} open files. Raise the limit (ulimit -n), read fewer files per run, or run as an ordinary user, which opens each file when it is read.`

A `--cores` run started as root opens every input file before it drops to `--user` (or `nobody`), so it can still read files only root may read. That holds one open file per input, and `{files}` inputs do not fit under the process limit `{soft_limit}` with room for the run's own files.

**What to do:** Raise the limit for the shell that starts sipnab (`ulimit -n 65536`), split the set across runs, or run as an ordinary user: then sipnab opens each file when it reads it.

**Exit code:** 2.

### `Expected format 'duration:N' or 'filesize:N', got '{s}'`

The `--autostop` value has no `:`. `{s}` is the value given. It must be a condition and a number separated by a colon. Printed after the prefix `Invalid --autostop: `.

**What to do:** Use `--autostop duration:N` (stop after N seconds) or `--autostop filesize:N` (stop when the output file reaches N MiB), for example `--autostop duration:60`.

**Exit code:** 2.

### `Expected format 'start-end' (e.g., '5060-5061'), got '{s}'`

A port range must be two port numbers joined by a single `-`, such as `5060-5061`.

- The value shown (`{s}`) did not split into exactly two parts at `-`. For example, it is a single port or three numbers.
- The same parser reads `--portrange`, `[capture] portrange`, `--ws-portrange` and `[capture] ws_ports`.
  - For the first two, the line starts with `Invalid --portrange:` or `Invalid [capture] portrange:`.
  - For the WebSocket pair, it starts with `invalid config value: --ws-portrange:` or `invalid config value: [capture] ws_ports:`.

**What to do:** Write the range as `START-END`. For one port, repeat it (`5060-5060`). sipnab accepts a start equal to the end.

**Exit code:** 2 when the value came from `--portrange` or `--ws-portrange`, and 1 when it came from `[capture] portrange` or `[capture] ws_ports`.

### `expected 'plain' or 'hmac', got '{other}'`

`--hep-auth-mode` accepts `plain` (sipnab sends the HEP shared secret as it is) or `hmac` (a signed, timestamped token, for sipnab-to-sipnab links only). `{other}` is the value you gave, in lowercase with surrounding spaces removed. sipnab ignores case and surrounding spaces.

**What to do:** Give `--hep-auth-mode plain` or `--hep-auth-mode hmac`, or leave the flag out for the default `plain`.

**Exit code:** 2.

### `expected 'udp', 'tcp' or 'tls', got '{other}'`

`--hep-send-transport` and `--hep-listen-transport` choose how HEP (the Homer encapsulation protocol that forwards captured packets) travels: `udp`, `tcp` or `tls`. `{other}` is the value you gave, in lowercase with surrounding spaces removed.

**What to do:** Give `udp`, `tcp` or `tls`, or leave the flag out for the default `udp`.

**Exit code:** 2.

### `--fail2ban writes nothing for detections carried by HEP: the inner addresses are the sender's claim, and a jail line would ban whatever address it chose. Pass --hep-allow-kill to admit them once the feed is authenticated (--hep-auth) and trusted.`

Startup warning for a run with `--fail2ban` that reads HEP without `--hep-allow-kill`.

- The run reads HEP with a HEP listener (`--hep-listen`), or with `--hep-parse`/`-E`.
- HEP (Homer Encapsulation Protocol) carries copies of SIP packets that another system sent.
- The source and destination addresses inside are whatever that sender wrote.
- sipnab therefore writes no jail line for a detection that arrived over HEP.

**What to do:**

- If you authenticate the HEP feed (`--hep-auth`) and trust it, add `--hep-allow-kill`. Then HEP-carried detections reach the jail log.
- Otherwise this warning is normal, and the jail log stays empty for HEP traffic.

**Exit code:** None. This is a warning, and the run continues.

### `--fail2ban writes scanner and registration-flood detections, but no detector is running, so this run will emit nothing. An empty jail log means 'nothing was detected', not 'nothing happened'. Add --kill-scanner to detect scanners (offline it only reports; it never transmits), --kill-ua <substring> to match a specific agent, -K/--kill-target <addr> to name one, or --reg-flood to detect registration floods.`

Startup warning for `--fail2ban` when none of the three producers of jail lines is active: no scanner detector (`--kill-scanner` or `[security] kill_scanner`), no `-K`/`--kill-target`, and no `--reg-flood`. With none of them, the run cannot write a jail line, so an empty jail log means sipnab looked for nothing.

**What to do:** Add one of these:

- `--kill-scanner` to detect scanners;
- `-K`/`--kill-target <addr>` (also `addr:port` or `addr:lo-hi`) to name a source;
- `--reg-flood` to detect registration floods.

`--kill-ua <pattern>` only adds a User-Agent pattern. sipnab accepts it only together with `--kill-scanner` or `[security] kill_scanner = true`.

**Exit code:** None. This is a warning, and the run continues.

### `Failed to read BPF filter file '{bpf_file}' (--bpf-file): {e}`

sipnab could not read the file named by `--bpf-file`. A BPF filter is the packet filter expression (tcpdump syntax) the kernel applies before sipnab sees packets. `{bpf_file}` is the path and `{e}` the reason.

**What to do:** Correct the path or the file's permissions, or give the filter expression on the command line instead of `--bpf-file`.

**Exit code:** 2.

### `Failed to start multi-device capture: {e}`

`--multi-device` could not start its captures. `{e}` is the reason. It is one of these:

- the device list given to `-d` is empty;
- the list has an empty entry (a doubled, leading or trailing comma);
- the list has a name containing a null byte;
- sipnab could not create a capture thread.

**What to do:** Give `-d` a comma-separated list of interface names with no empty entries, for example `-d eth0,docker0 --multi-device`.

**Exit code:** 1.

### `{flag} '{}': file is empty`

A secret file given with `--hep-auth-file` or `--metrics-auth-file` is empty or holds only whitespace. `{flag}` is the flag, and the quoted value is the path. sipnab refuses to start rather than run without authentication. The line starts with `HEP auth:` or `metrics auth:`.

**What to do:** Write the secret into the file, or remove the flag if you do not want a secret.

**Exit code:** 2.

### `--fraud-destination {bad:?} is not a destination sipnab can match: give ISO 3166-1 alpha-2 codes the dial plan labels (NANP for +1 numbers), comma-separated`

One entry in the comma-separated `--fraud-destination` list is not a destination label sipnab knows.

- `{bad:?}` is the first such entry, shown in double quotes.
- Labels are the two-letter ISO 3166-1 alpha-2 country codes that sipnab's dial plan uses. sipnab compares them without regard to case.
- Numbers starting with +1 carry the label `NANP` (North American Numbering Plan). So sipnab does not accept `US`.

**What to do:** Replace the named entry with a label from the dial plan, such as `GB` or `DO`. Use `NANP` for any +1 destination. Separate entries with commas.

**Exit code:** 2.

### `HEP auth: {e}`

sipnab could not resolve the HEP authentication secret. `{e}` names the source: a `--hep-auth-file '<path>'` that sipnab cannot read or that is empty, or an empty value in `--hep-auth` or the `SIPNAB_HEP_AUTH` environment variable. sipnab refuses an empty secret because it would authenticate any sender that presents an empty one.

**What to do:** Put a non-empty secret in the file or the flag, or remove `--hep-auth`/`--hep-auth-file` and unset `SIPNAB_HEP_AUTH`.

**Exit code:** 2.

### `--hep-listen requires the 'hep' feature (not compiled in)`

`--hep-listen` receives packets over HEP (Homer Encapsulation Protocol). This sipnab build does not include the `hep` feature, so it cannot listen for HEP. sipnab refuses the run before it opens the capture.

**What to do:** Use a sipnab build that includes the `hep` feature, or capture with `-d` or `-I` instead.

**Exit code:** 2.

### `HEP support requires --features hep`

The run asks for HEP, and this sipnab build does not include the `hep` feature. `--hep-send` (send captured packets to a HEP collector) and `--hep-parse` or `[capture] hep_parse = true` (decode HEP packets) both print this message. sipnab refuses the run before it opens the capture.

**What to do:** Use a sipnab build that includes the `hep` feature. Or remove `--hep-send` and `--hep-parse`, and set `[capture] hep_parse = false` or pass `--no-hep-parse`.

**Exit code:** 2.

### `Ignoring invalid --kill-target '{spec}': {e}`

A `-K`/`--kill-target` value failed to parse while sipnab built the detectors, and sipnab skips that one target. `{spec}` is the value, and `{e}` is the reason. The code notes that this is a fallback: sipnab checks the same values at startup and refuses a malformed value before the capture opens.

**What to do:** Give the target as `ADDR`, `ADDR:PORT` or `ADDR:LO-HI`. An IPv6 address with a port goes in brackets, for example `[::1]:5060`.

**Exit code:** None. sipnab logs the error, and the run continues.

### `--input/-I and --hep-listen/-L cannot run together. This is a security refusal, not a scheduling one: packets read from a file carry historical addresses belonging to third parties who are not part of this analysis, and sipnab keeps them off the active response path by refusing to transmit for a FILE run at all. A composite source would remove that refusal while the per-packet gate still admitted them. Read the capture in its own run, and point -L at a separate sipnab.`

sipnab refuses to read a capture file (`-I`) and listen for HEP (`-L`) in one run. HEP is Homer Encapsulation Protocol, a format for mirroring SIP to a collector.

- sipnab never transmits during a file run.
- Combining the two sources would remove that refusal.
- Packets from the file carry other parties' historical addresses. They could still reach the active response path.

**What to do:** Run two separate sipnab processes: one that reads the file with `-I`, and one that listens with `-L`.

**Exit code:** 2.

### `Internal error building the --calls-only filter: {e}`

`-c`/`--calls-only` keeps only INVITE dialogs. It joins the expression `method == 'INVITE'` to the run's filter with `AND`. That combined expression did not parse.

- sipnab has already checked any `--filter` expression by this point. So this indicates a fault in sipnab.
- `{e}` is the parser's error.

**What to do:** Report the message with the command line. Running without `-c` avoids this step.

**Exit code:** 2.

### `--compare-captures: {e}`

`--compare-captures <A> <B>` could not compare the two files. `{e}` says which of these happened:

- `'{a}' and '{b}' are the same file; a capture compared with itself differs from itself nowhere`. Exit code 2.
- A dimension outside the `--count-by` set. Exit code 2. sipnab refuses it before it reads any file.
- `'{name}' yielded no dialogs and reported: {reason}. Refusing to diff against it — every bucket would appear to have collapsed to zero, which is a finding that is not there.` The file is missing, is not a capture, or holds no SIP dialog. Exit code 1.

**What to do:** Name two different files. For a file that yielded nothing, check the reason it gives: a path that does not exist, or a capture taken where no SIP passed.

**Exit code:** 2 for the same file or a dimension, 1 for a file that yields nothing.

### `--find-in-files needs something to find: give --filter, or a diagnostic alias such as --problems, to say which dialogs to look for`

`--find-in-files` reports the files that hold the dialogs a filter selects, and the command line gave no filter: no `--filter`, no diagnostic alias, and no `--since` or `--until`.

**What to do:** Say what to look for, for example `--filter 'call_id == "abc@example.com"'` to find one call, or `--problems` to find the files with failed calls.

**Exit code:** 2.

### `--find-in-files: {why}`

`--find-in-files` could not list a directory named on the command line. `{why}` names the directory and the operating system's reason.

**What to do:** Check that the path exists and that this user may read it.

**Exit code:** 1.

### `--expect: {why}`

`--expect` judges `lint_errors` rules with the lint suppression file in force, and sipnab could not read it. `{why}` names the file (`--lint-suppress-file`, or a `.sipnab-lint-suppress` found beside the capture) and the reason. sipnab prints no verdict.

**What to do:** Fix or remove the suppression file, or name a readable one with `--lint-suppress-file`.

**Exit code:** 2.

### `--expect {}: {e}`

The suite file `{}` holds a rule the evaluator refused when it judged the capture: `{e}` names the rule by its index and says why. sipnab checks every rule before it reads the capture, so this is rare: a rule whose filter compiles with the default thresholds and not with the ones the run's configuration sets.

**What to do:** Fix the rule `{e}` names. The suite's exit code `2` means no verdict.

**Exit code:** 2.

### `--export-audio: {why}`

`--export-audio <CALL-ID>` could not write the call's audio. `{why}` says which of these happened:

- The capture holds neither a SIP dialog nor an RTP stream with that Call-ID. The message is `no SIP dialog and no RTP stream associated with call_id '{call_id}' in this capture`.
- The call has no RTP streams, or none with audio sipnab can decode. The message names what sipnab measured and why it kept nothing to decode.
- sipnab could not create the file. An existing file is one cause: sipnab never replaces one.

sipnab writes no file in any of these cases.

**What to do:** For an unknown Call-ID, run with `--report` to list the Call-IDs this run holds. For nothing to decode, check the message: a `--snaplen` too short for the payload is the usual cause. For a file that exists, name another with `--export-audio-out`, or remove the old one.

**Exit code:** 1.

### `--rates-by: {why}`

`--rates-by` asked the metric table for a metric it has no way to compute. Every metric `--rates-by` computes comes from that same table, so this message means a defect in sipnab, not in the capture or the command line. sipnab prints no metrics.

**What to do:** Report it with the command line and the sipnab version. `--count-by` with the same dimension still counts the dialogs.

**Exit code:** 1.

### `--timeline: {e}`

`--timeline` read the capture, but its calls span more intervals of the width than one histogram holds. `{e}` names how many intervals the span needs, the most a histogram holds (100,000), and a width that fits, for example `the dialogs span 5256001 intervals of 60 s, and one histogram holds at most 100000; a width of 3154 s or more fits`. sipnab prints no histogram.

**What to do:** Run again with the width it names, or a wider one: `--timeline=3154`. To keep a narrow width, narrow the calls instead with `--since` and `--until`.

**Exit code:** 1.

### `--until {} is not after --since {}: the window [--since, --until) would hold no instant`

`--since` and `--until` keep the dialogs whose first message falls at or after `--since` and before `--until`.

- The `--until` time you gave is the first `{}`.
- It is the same as or earlier than the `--since` time, the second `{}`.
- So no instant is in the window.
- sipnab prints both in [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) UTC.

**What to do:** Give an `--until` time later than the `--since` time. Or drop one of the two flags for a window open on that side.

**Exit code:** 2.

### `--since/--until narrow the batch outputs and require -N/--no-tui mode. In the TUI, set the time range in the call list's filter dialog`

`--since` and `--until` narrow the batch outputs: `--report`, `--json-dialogs`, the per-message stream and the queries. The terminal UI shows none of them. You gave one of the flags without `-N`, so the run would start the terminal UI.

**What to do:** Add `-N` to run headless. Or drop the flags and set the time range in the filter dialog of the call list in the terminal UI.

**Exit code:** 2.

### `Internal error building diagnostic filter: {e}`

sipnab expands the diagnostic alias flags (`--problems`, `--slow-setup`, `--short-calls`, `--one-way`, `--nat-issues`) into one filter expression, and that combined expression did not parse. sipnab has already checked any `--filter` expression by this point, so this indicates a fault in sipnab's own alias expansion. `{e}` is the parser's error.

**What to do:** Report the message with the command line. Running without the diagnostic alias flags avoids this step.

**Exit code:** 2.

### `Invalid {portrange_source}: {e}`

sipnab could not parse the SIP port range. `{portrange_source}` names where it came from: `--portrange` or `[capture] portrange`. `{e}` is the reason: the value is not `start-end`, a port is not a number from 0 to 65535, or the start is above the end.

**What to do:** Use the form `start-end`, for example `--portrange 5060-5061`, in the flag or the config key.

**Exit code:** 2 when the value came from `--portrange`, and 1 when it came from `[capture] portrange`.

### `invalid alert rule '{input}': {reason}`

An alert rule from `--alert` or `[security] alert` does not follow the grammar `<name>:<threshold>/<window>[:<cooldown>]`.

- `{input}` is the rule.
- `{reason}` names the part that failed:
  - a missing `:` or `/`;
  - an empty name;
  - a threshold that is not a whole number;
  - a window or cooldown without an `s`, `m` or `h` suffix.
- The line starts with `--alert:` or `[security] alert:`.
- sipnab reads an entry without `:` as a channel name, and checks it separately.

**What to do:** Write the rule as in `scanner:10/1m` or `reg-flood:50/10s:5m`: a finding name, a count, `/`, a window with `s`, `m` or `h`, and optionally `:` and a cooldown.

**Exit code:** 2 when the value came from `--alert`, and 1 when it came from `[security] alert`.

### `Invalid --autostop: {e}`

sipnab could not use the `--autostop` value. `{e}` is the reason. It is one of these:

- the value has no `:`;
- the number is not a whole number;
- the number is 0;
- the condition is not `duration` or `filesize`.

**What to do:** Use `--autostop duration:N` (seconds) or `--autostop filesize:N` (MiB), with N a whole number above 0.

**Exit code:** 2.

### `Invalid --capture-tunnels port '{text}': expected a comma-separated list of UDP ports in 1-65535, e.g. --capture-tunnels={TUNNEL_PORTS_DEFAULT_LIST}`

An entry in the `--capture-tunnels` list is not a UDP port from 1 to 65535. `{text}` is the entry as given, after trimming spaces. An empty entry also produces this message. `{TUNNEL_PORTS_DEFAULT_LIST}` is the default list, `2152,4789,6081`.

**What to do:** Give a comma-separated list of port numbers, for example `--capture-tunnels=2152,4789,6081`. Or give the flag with no value to use the default.

**Exit code:** 2.

### `invalid CIDR '{input}': {reason}`

A `--hep-allow` entry is not a valid address or CIDR range. That flag is the list of senders that may deliver HEP to `--hep-listen`.

- `{input}` is the entry.
- `{reason}` says what failed:
  - an invalid IP address;
  - an invalid prefix length;
  - a prefix longer than 32 (IPv4) or 128 (IPv6).
- The line starts with `Invalid --hep-allow CIDR '<entry>':`.
- sipnab accepts a bare address without `/`, and reads it as that one host.

**What to do:** Write each entry as an address (`192.0.2.40`) or an address with a prefix length (`198.51.100.0/24`, `2001:db8::/32`).

**Exit code:** 2.

### `Invalid --duration: {e}`

sipnab could not parse the `--duration` value. `{e}` is the reason: the value is empty, the number is not a whole number, or the result is too large. The accepted forms are a whole number of seconds, optionally followed by `s`, `m` or `h`.

**What to do:** Use a form such as `--duration 30`, `--duration 30s`, `--duration 5m` or `--duration 1h`.

**Exit code:** 2.

### `Invalid --duration: '{d}' is zero; give a positive duration`

`--duration` parsed to zero seconds (`{d}` is the value given). A zero duration would stop the capture before its first packet and exit 0.

**What to do:** Give a positive duration, for example `--duration 30`, `--duration 30s`, `--duration 5m` or `--duration 1h`.

**Exit code:** 2.

### `Invalid --filter expression: {e}`

The `--filter` expression did not parse. `--filter` takes sipnab's dialog filter language, or the name of a diagnostic alias such as `problems`. `{e}` is the parser's error.

**What to do:** Correct the expression at the point the error names, or use one of the alias names.

**Exit code:** 2.

### `Invalid filter pattern: {e}`

A SIP matching pattern did not compile as a regular expression. The patterns come from `-e/--match`, `--from`, `--to`, `--contact`, `--ua`, or the config file's `[filter] from` and `[filter] to`. `{e}` names which pattern failed.

**What to do:** Correct the named pattern's regular expression syntax, or quote it so the shell passes it unchanged.

**Exit code:**

- 2 when the command line includes any of `--match`, `--from`, `--to`, `--contact` or `--ua`;
- 1 otherwise (patterns from the config file).

### `Invalid --hep-allow CIDR '{cidr}': {e}`

A `--hep-allow` value is not a valid address range. `--hep-allow` lists the senders the HEP listener accepts, as CIDR notation (an IP address with an optional `/prefix` length). `{cidr}` is the value and `{e}` the reason: an invalid IP, an invalid prefix length, or a prefix longer than the address family allows (32 for IPv4, 128 for IPv6).

**What to do:** Give an address such as `192.0.2.40` (one host) or a range such as `192.0.2.0/24`.

**Exit code:** 2.

### `Invalid --ws-portrange: {e}`

The SIP over WebSocket port range that `--ws-portrange` gives is not usable. `{e}` says what is wrong:

- the value is not two ports joined by `-`;
- one side is not a port number from 0 to 65535;
- the start is higher than the end.

**What to do:** Give the range as `START-END` with the lower port first, for example `8080-8443`. Or remove the flag for the shipped ports.

**Exit code:** 2.

### `is a MOS and must be at most {}, got {v}`

`--mos-warn` and `--mos-bad` set MOS (Mean Opinion Score, a call-quality score) boundaries for the quality color column. No score can reach a boundary above the top of the scale. `{}` is that maximum, 5, and `{v}` is the value you gave.

**What to do:** Give a number from 0 to 5.

**Exit code:** 2.

### `is a percentage and must be <= 100, got {v}`

`--duration-asymmetry-pct` is a percentage, and the value you gave is above 100. `{v}` is the value as read.

**What to do:** Give a number greater than 0 and no greater than 100.

**Exit code:** 2.

### `is a percentage and must be at most 100, got {v}`

`--loss-warn-pct` and `--loss-bad-pct` are packet-loss percentages for the quality color column, and the value you gave is above 100. `{v}` is the value as read.

**What to do:** Give a number from 0 to 100.

**Exit code:** 2.

### `--kill-target '{spec}': {e}`

sipnab could not read a `-K`/`--kill-target` value. sipnab checks each value at startup.

- `{spec}` is the value as you gave it.
- `{e}` is the reason, such as:
  - an empty value;
  - an address that is not IPv4 or IPv6;
  - an unclosed `[`;
  - a port that is not a number from 0 to 65535;
  - a port range whose start is above its end.

**What to do:** Write each value in one of these forms:

- an address (`192.0.2.10`);
- an address with a port or port range (`192.0.2.10:5060` or `192.0.2.10:5060-5070`);
- an IPv6 address in brackets, with an optional port (`[2001:db8::1]:5060`).

**Exit code:** 2.

### `-K/--kill-target asks sipnab to answer every SIP request from the source it names, and --kill-scanner-detect-only (or [security] kill_scanner_detect_only = true) asks sipnab to answer nothing. Remove -K to detect scanners without answering them, or remove detect-only (--no-kill-scanner-detect-only overrides the config key) to answer the named source.`

You asked for two things that cannot both happen. `-K`/`--kill-target` sends a SIP response to every request from the source you named. Detect-only (`--kill-scanner-detect-only`, or `kill_scanner_detect_only = true` in `[security]`) means sipnab sends nothing. sipnab refuses the run rather than ignore one of them.

**What to do:** Choose one:

- To detect scanners and send nothing, remove `-K`.
- To answer the named source, remove `--kill-scanner-detect-only`. If the configuration file sets `kill_scanner_detect_only = true`, add `--no-kill-scanner-detect-only` for this run, or remove the key.

**Exit code:** 2.

### `--multi-device and --hep-listen/-L cannot run together yet. One interface plus one HEP listener is supported; a device LIST plus a listener is not, because sipnab correlates a HEP-delivered dialog to a locally captured stream by SDP media endpoint alone and that index carries no node dimension — two sources advertising the same address and port would overwrite each other. Drop --multi-device, or drop -L.`

You cannot combine `--multi-device` with a HEP listener (`-L`). That flag takes a comma-separated device list given to `-d`.

- sipnab matches a HEP-delivered call to locally captured media by the SDP media address and port alone.
- With several capture devices, two sources could advertise the same address and port. They would overwrite each other.
- sipnab supports one interface plus one HEP listener.

**What to do:** Remove `--multi-device` and capture on one interface beside `-L`, or remove `-L`.

**Exit code:** 2.

### `--multi-device and -I/--input cannot run together: --multi-device captures live interfaces (-d), and -I reads a saved capture. Drop --multi-device to read the file, or drop -I to capture the devices.`

`--multi-device` opens one capture per network interface named with `-d`, and `-I` reads a saved capture. sipnab refuses the two together before it opens anything.

**What to do:** To read the file, remove `--multi-device`. `--cores` then reads it in parallel. To capture the interfaces, remove `-I`.

**Exit code:** 2.

### `--multi-device requires a live capture device (-d)`

`--multi-device` opens one capture per network interface in the device list, so it needs a live interface source. This run's source is a uprobe source (`--uprobe-tls`/`--uprobe-library`), not a live interface. sipnab refuses a file given with `-I` earlier, with the message above.

**What to do:** Name the interfaces with `-d`, for example `-d eth0,docker0 --multi-device`, and remove the uprobe flags. Or remove `--multi-device`.

**Exit code:** 2.

### `must be a finite number > 0, got {v}`

A diagnosis threshold flag needs a finite number greater than 0. `{v}` is the value as read, which was 0, negative, `nan` or infinite. The flags are `--pdd-threshold`, `--ack-timeout`, `--no-final-response-timeout`, `--duration-asymmetry-secs` and `--duration-asymmetry-pct`.

**What to do:** Give a positive number for the flag that the error names.

**Exit code:** 2.

### `must be a finite number of 0 or more, got {v}`

A measurement boundary or declared delay needs a finite number of 0 or more. `{v}` is the value as read, which was negative, `nan` or infinite. The flags are `--one-way-delay`, `--jitter-warn-ms`, `--jitter-bad-ms`, `--rtt-warn-ms`, `--rtt-bad-ms`, `--mos-warn`, `--mos-bad`, `--loss-warn-pct` and `--loss-bad-pct`.

**What to do:** Give 0 or a positive number for the flag that the error names.

**Exit code:** 2.

### `--names {f:?} cannot be read: {e}`

sipnab cannot open a file given to `--names`, or the path is a directory. That flag takes an `/etc/hosts`-format file that maps IP addresses to names.

- `{f:?}` is the path in quotes and `{e}` is the reason.
- sipnab refuses instead of running without the names you asked it to use.

**What to do:** Correct the path, make the file readable by the user running sipnab, or remove that `--names` argument.

**Exit code:** 1.

### `no --hep-listen address to plan from`

An internal check: sipnab was building the HEP source without a `--hep-listen` address. Every caller checks for `-L` first, so this does not happen in normal use. The check exists so that a future change cannot fall back to a default listen address nobody asked for.

**What to do:** Report the message together with the command line that produced it.

**Exit code:** 2.

### `--notes {path}: {refusal}`

In a run that starts the TUI, sipnab loads the `--notes` file before any capture opens and refused it. `{path}` is the `--notes` value and `{refusal}` is the reason: sipnab cannot read the file, a line is not an accepted note, or the file holds more than 10,000 notes. sipnab accepts a file that does not exist yet.

**What to do:** Correct the line or the permissions the message names, or point `--notes` at a new file name.

**Exit code:** 2.

### `--notes names the notes for --write-annotated or the TUI's notes file, and this run is neither: nothing would read them`

`--notes` names a notes file. Only `--write-annotated` and the interactive TUI read it.

- This run is neither. For example, it uses `-N`/`--no-tui`, MCP, or `--cores` with `-I`.
- So nothing would read the notes, and sipnab refuses the flag.

**What to do:** Remove `--notes`, or use it with `--write-annotated <OUT> -I <capture>`, or in a run that starts the TUI.

**Exit code:** 2.

### `Output flags ({}) require -N/--no-tui mode (or --call-report, or --export-vcon)`

The flags listed in parentheses print their results to standard output. The interactive terminal interface (TUI) uses standard output. You gave them on a run that starts the TUI.

The list can include `--json`, `--json-dialogs`, `--json-pretty`, `--report`, `--stun`, `--json-stun`, `--analyze`, `--json-analyze`, `--yang-analyze`, `--hexdump`, `--fail2ban`, `--group-by` and `--recommend-block`.

**What to do:** Add `-N` (`--no-tui`) to run without the TUI. A run with `--call-report` or `--export-vcon` is also accepted.

**Exit code:** 2.

### `Port range start ({start}) > end ({end})`

A port range has a first port larger than the second.

- `{start}` and `{end}` are the two numbers as read.
- The same parser reads `--portrange`, `[capture] portrange`, `--ws-portrange` and `[capture] ws_ports`.
- The line starts with the name of the setting that held the value.

**What to do:** Put the lower port first, for example `5060-5080` rather than `5080-5060`.

**Exit code:** 2 when the value came from `--portrange` or `--ws-portrange`, and 1 when it came from `[capture] portrange` or `[capture] ws_ports`.

### `quality-threshold is a MOS on the 1.0-5.0 scale and must be a finite number in that range, got {v}`

`--quality-threshold` is the MOS (Mean Opinion Score, 1.0 to 5.0) that quality alerts and `--on-quality-exec` use. `{v}` is the value as read, which was outside 1.0-5.0, `nan` or infinite.

**What to do:** Give a number from 1.0 to 5.0, or leave the flag out for the default 3.0.

**Exit code:** 2.

### `Skipping invalid alert rule '{value}': {e}`

An `--alert` (or `[security] alert`) value containing `:` is not a valid alert rule, and sipnab skipped it. `{value}` is the value, and the text after it is the parser's reason.

**What to do:** Write the rule as `name:threshold/window`.

**Exit code:** None. This is a warning, and the run continues.

### `start and end must differ; "{start}-{end}" is a zero-width window that would treat every call as off-hours`

A business-hours window has the same start and end hour. sipnab uses this window to flag calls placed outside office hours.

- `{start}` and `{end}` are the two hours.
- Such a window has no length, so every call would count as off-hours.
- The window comes from one of two places:
  - `--business-hours` (the line starts with `--business-hours`);
  - `[security] business_hours` (the line starts with `invalid config value: [security] business_hours`).

**What to do:** Give two different whole hours from 0 to 23, such as `8-18`, or `22-6` for an overnight window.

**Exit code:** 2 when the value came from `--business-hours`, and 1 when it came from `[security] business_hours`.

### `{inline_flag}: the value is empty. An empty secret authenticates any peer that presents an empty one, and satisfies the bind policy while doing it -- set a real secret or unset the flag`

An inline secret is empty or holds only whitespace. `{inline_flag}` is `--hep-auth (or SIPNAB_HEP_AUTH)` or `--metrics-auth`. An empty secret matches a peer that sends an empty one, and it still counts as configured authentication, so sipnab refuses it. The line starts with `HEP auth:` or `metrics auth:`.

**What to do:** Set a non-empty secret, or unset the flag or environment variable, as the message says.

**Exit code:** 2.

### `--tui-audit-file records what an operator did in the TUI, and -N/--no-tui runs no TUI. Use --run-provenance-file to record how a headless run was invoked, or drop -N`

`--tui-audit-file` writes a record of the actions an operator takes in the interactive terminal interface (TUI). `-N`/`--no-tui` runs without that interface, so there would be nothing to record. `--run-provenance-file` records how you started a run, and it works without the TUI.

**What to do:** Remove `-N` to run the TUI with its audit file, or replace `--tui-audit-file` with `--run-provenance-file FILE` for a headless run.

**Exit code:** 2.

### `{from}: Unknown alert channel '{source}': expected one of {}, or a rule written name:threshold/window`

sipnab reads an alert source that contains no `:` as an alert channel name, and `{source}` is not one. `{from}` is where the value came from (`--alert` or `[security] alert`). The list after "expected one of" is `syslog, json, exec` (compared without regard to case).

**What to do:** Use `syslog`, `json` or `exec` as the channel, or write a rule as `name:threshold/window`, for example `scanner:10/1m`.

**Exit code:** 2 when the value came from `--alert`, and 1 when it came from `[security] alert`.

### `Unknown alert channel '{}'. Valid channels: syslog, json, exec. (A value containing ':' is treated as an alert rule.)`

sipnab reads an `--alert` (or `[security] alert`) value without `:` as a channel name, and this one is not `syslog`, `json` or `exec`. sipnab ignored it.

**What to do:** Use `syslog`, `json` or `exec`, or write an alert rule as `name:threshold/window`.

**Exit code:** None. This is a warning, and the run continues.

### `{from}: Unknown alert rule '{}': expected one of {} (reg-flood is accepted for reg_flood)`

An alert rule parsed, but its name is not a finding kind any detector produces. `{from}` is `--alert` or `[security] alert`, the first placeholder is the rule name, and the list is `digest, fraud, reg_flood, scanner`. sipnab accepts `reg-flood` as another spelling of `reg_flood`.

**What to do:** Use one of the listed names in the rule, for example `--alert reg_flood:20/1m`.

**Exit code:** 2 when the value came from `--alert`, and 1 when it came from `[security] alert`.

### `Unknown autostop condition: '{key}'. Expected 'duration' or 'filesize'`

The `--autostop` condition name is not one sipnab knows. `{key}` is the text before the colon. Printed after the prefix `Invalid --autostop: `.

**What to do:** Use `duration` or `filesize`, for example `--autostop duration:60` or `--autostop filesize:100`.

**Exit code:** 2.

### `{from}: {e}`

sipnab could not parse an `--alert` (or `[security] alert`) rule. `{from}` names where the rule came from, and the text after it is the parser's reason.

**What to do:** Write the rule as `name:threshold/window`.

**Exit code:** 2 when the value came from `--alert`, and 1 when it came from `[security] alert` in the configuration file.

## Configuration file

### `cannot read config file {path}: {source}`

sipnab found a config file but could not read it as text.

- The file is one that `-f`/`--config` or `$SIPNAB_CONFIG` names, or one at a default location.
- `{path}` is the file.
- `{source}` is the operating-system or read error. Examples are permission denied, a directory, or content that is not UTF-8.

**What to do:** Do one of these:

- Give the user running sipnab read access to the file.
- Point `--config` at a regular text file.
- Start with `-F`/`--no-config` to use the built-in defaults.

**Exit code:** 1.

### `cannot serialize config: {0}`

`-D`/`--dump-config` could not turn the loaded configuration back into TOML text. `{0}` is the serializer's reason. sipnab logs it as `Failed to dump config: cannot serialize config:` followed by the reason. `--dump-config` is the only caller of this conversion.

**What to do:** The text after the colon is the serializer's reason. Only `--dump-config` converts the configuration back to TOML, so this does not affect a run without that flag.

**Exit code:** 1.

### `[capture] node_name is empty; give a name, or remove the key for the hostname`

The `[capture] node_name` key holds an empty string. `node_name` is the name this machine reports in `capture_identity.node`, and sipnab refuses an empty one. The printed line starts with `invalid config value: `.

**What to do:** Write a name between the quotes, or delete the `node_name` line so sipnab uses the system hostname.

**Exit code:** 1.

### `config file not found: {path}`

The file that `-f`/`--config` names does not exist. `{path}` is the path you gave. A missing file named by `$SIPNAB_CONFIG` is not an error: the search moves on to the default locations.

**What to do:** Correct the path you give to `--config`, or leave the flag out to use the default search order.

**Exit code:** 1.

### `could not load names file {f}: {e}`

sipnab could not read a names file when it loaded names. A names file is an `/etc/hosts`-format file of IP-to-name mappings from `--names` or `[names] hosts_file`.

- `{f}` is the path, and `{e}` is the read error.
- Startup already refuses a names file it cannot read. So this appears when the file became unreadable after that check.
- The run continues without the names in that file.

**What to do:** Give the user sipnab runs as read access to the file, and restart sipnab.

**Exit code:** None. This is a warning, and the run continues.

### `create {}: {e}`

sipnab could not create the folder that holds the configuration file. This happened while saving from the terminal UI, either the column layout (F10 selector) or a name for an address.

- `{}` is the folder path.
- `{e}` is the operating system's reason.
- sipnab writes nothing.

**What to do:** Create the folder yourself, or give the user running sipnab permission to create it, then save again.

**Exit code:** None. sipnab shows the error on the terminal UI status line, and the run continues.

### `[diagnosis] cn_suppression_ratio is a share of the packets and must be a finite number > 0 and <= 1, got {r}`

`[diagnosis] cn_suppression_ratio` is a share of a call's packets, as a fraction of 1.

- That share must be comfort noise before sipnab accepts comfort noise as the reason for one-way audio. Comfort noise is the background-noise packets a phone sends during silence.
- The value must be above 0, at most 1, and a finite number (not infinity or NaN, not-a-number).
- `{r}` is the value in the file.
- The printed line starts with `invalid config value: `.

**What to do:** Set a number above 0 and at most 1, for example the default `0.3`, or remove the key.

**Exit code:** 1.

### `[diagnosis] duration_asymmetry_pct is a percentage and must be <= 100, got {pct}`

`[diagnosis] duration_asymmetry_pct` is the percentage difference between the durations of a call's two legs that counts as asymmetric. sipnab refuses values above 100. `{pct}` is the value in the file. The printed line starts with `invalid config value: `.

**What to do:** Set a number above 0 and at most 100, for example the default `5`, or remove the key.

**Exit code:** 1.

### `[diagnosis] late_media_ms must be > 0, got {ms}`

`[diagnosis] late_media_ms` is how many milliseconds after the `200 OK` the media may start before sipnab reports it as late. `{ms}` is the value in the file, which is 0 or below. The printed line starts with `invalid config value: `.

**What to do:** Set a whole number above 0, for example the default `500`, or remove the key.

**Exit code:** 1.

### `[diagnosis] {key} must be a finite number > 0, got {v}`

A `[diagnosis]` threshold is 0, negative, infinity or NaN (not-a-number).

- `{key}` is one of `post_dial_delay_secs`, `ack_timeout_secs`, `no_final_response_secs`, `duration_asymmetry_pct` or `duration_asymmetry_secs`.
- `{v}` is its value.
- These thresholds decide when sipnab reports a call as faulty.
- The printed line starts with `invalid config value: `.

**What to do:** Set the named key to a number above 0, or remove it. The defaults are 11, 32, 180, 5 and 2, in the order listed.

**Exit code:** 1.

### `[display] color must be one of {}, got {c:?}`

`[display] color` accepts only `auto`, `always` or `never`, in lowercase. `{}` is that list, and `{c:?}` is the value in the file, in double quotes. The printed line starts with `invalid config value: `.

**What to do:** Set `color` to `auto`, `always` or `never`, or remove the key.

**Exit code:** 1.

### `[display] from_to must be one of default, host-port, user, user-host-port, got {m:?}`

`[display] from_to` sets how the terminal UI shows the From and To columns. sipnab accepts only `default`, `host-port`, `user` and `user-host-port`, in lowercase, and `{m:?}` is the value in the file. sipnab checks this key only in builds that include the terminal UI. The printed line starts with `invalid config value: `.

**What to do:** Set `from_to` to one of the four values, or remove the key.

**Exit code:** 1.

### `[display] view_filter_detail must be one of summary, full, got {m:?}`

`[display] view_filter_detail` names a display mode the terminal UI does not have.

- `{m:?}` is the value in the file.
- `summary` shows the filter-dialog (F7) part of the view filter as a short summary on status line 3.
- `full` shows the whole expression.
- sipnab checks this key only in builds that include the terminal UI.
- The printed line starts with `invalid config value: `.

**What to do:** Set `view_filter_detail` to `summary` or `full`, or remove the key.

**Exit code:** 1.

### `[display] is not a table`

You saved the column layout from the terminal UI (the `s` action in the F10 column selector). sipnab could not add `visible_columns` to the configuration file.

- The reason: the file defines `display` as a plain value instead of a `[display]` table (section).
- sipnab writes nothing.
- The status line shows `Save columns failed: invalid config value: [display] is not a table`.

**What to do:** Edit the configuration file so `display` is a `[display]` section, then save again.

**Exit code:** None. sipnab shows the error on the terminal UI status line, and the run continues.

### `[display] visible_columns names {col:?}, which is not a column; the columns are {}`

`[display] visible_columns` lists the call-list columns the terminal UI shows.

- `{col:?}` is an entry that matches no column.
- `{}` lists the valid names: `#`, `Method`, `From`, `To`, `Source`, `Destination`, `State`, `Msgs`, `Date`, `PDD` and `Duration`.
- sipnab compares names without regard to case.
- sipnab checks this key only in builds that include the terminal UI.
- The printed line starts with `invalid config value: `.

**What to do:** Correct or remove the named entry so every entry is one of the listed column names.

**Exit code:** 1.

### `Failed to dump config: {e}`

`--dump-config` prints the effective configuration as TOML, and converting the loaded configuration to TOML failed. `{e}` is the serializer's error.

**What to do:** Report the message together with the config file that produced it.

**Exit code:** 1.

### `[filter] {key}: {problem}`

`[filter] from` or `[filter] to` holds a pattern that does not compile.

- These keys hold a regular expression (a text-matching pattern). sipnab matches it against the From or To header.
- `{key}` is `from` or `to`.
- `{problem}` starts with `failed to compile pattern` and the pattern. The regular-expression library's reason follows, such as a syntax error or a pattern over the size limit.
- The printed line starts with `invalid config value: `.

**What to do:** Correct the pattern so it is a valid regular expression, or remove the key. Characters such as `(`, `[` and `+` have a special meaning and need a `\` before them to match literally.

**Exit code:** 1.

### `ignoring invalid [display] from_to = {s:?}`

`[display] from_to` holds a value that names no From/To column mode, and sipnab ignores it. sipnab refuses such a value when it loads the config file, with the message `[display] from_to must be one of default, host-port, user, user-host-port`. sipnab reaches this warning only for a configuration built without loading a file.

**What to do:** Set `[display] from_to` to one of `default`, `host-port`, `user` or `user-host-port`, or use the matching command-line flag, which takes precedence.

**Exit code:** None. This is a warning, and the run continues.

### `ignoring invalid IP key {ip_str:?} in [names.manual]`

A key in the `[names.manual]` table (manual IP-to-name mappings) is not an IP address. So sipnab skips the entry.

- `{ip_str:?}` is the key.
- The `sipnab` command checks this table at startup. It first refuses such a key with `invalid config value: [names.manual] key "<key>" is not an IP address` (exit 1).
- So this warning appears only for a config that reached `sipnab::app::build_resolver` without that check.

**What to do:** Write each key as an IPv4 or IPv6 address, for example `"192.0.2.5" = "pbx1"`.

**Exit code:** None. This is a warning, and the run continues.

### `ignoring invalid name for {ip_str:?} in [names.manual]`

A name in the `[names.manual]` table is not usable. So sipnab skips the entry.

- `{ip_str:?}` is the IP address the name belongs to.
- sipnab refuses a name that:
  - is empty;
  - is longer than 253 bytes;
  - contains a NUL or another control character.
- The `sipnab` command checks this table at startup. It first refuses such a name with `invalid config value: [names.manual] name <name> is not a valid name` (exit 1).
- So this warning appears only for a config that reached `sipnab::app::build_resolver` without that check.

**What to do:** Give a non-empty name of at most 253 bytes with no control characters.

**Exit code:** None. This is a warning, and the run continues.

### `invalid config {path}: {source}`

The config file at `{path}` is not valid TOML. Or a value has the wrong type for its key, for example text where the key needs a number.

- `{source}` is the TOML parser's description of the problem.
- `<inline>` appears instead of a path when the text did not come from a file.

**What to do:** Correct the TOML syntax or the value type that `{source}` describes, or start with `-F`/`--no-config` to skip the file.

**Exit code:** 1.

### `Invalid config filter expression ([filter] expression): {e}`

The config file's `[filter] expression` did not parse as a dialog filter expression or an alias name. sipnab reads it only when the command line has no `--filter` and no diagnostic alias flags. `{e}` is the parser's error.

**What to do:** Correct `[filter] expression` in the config file, or remove the key. A `--filter` given on the command line replaces it.

**Exit code:** 1.

### `invalid config value: {0}`

The config file parsed as TOML, but a value failed the checks sipnab applies.

- `{0}` names the section and key, and says what is wrong. For example:
  - a number out of range;
  - an unknown kind;
  - an unreadable `hosts_file`;
  - a `${NAME}` that sipnab cannot expand, which also names the file.
- sipnab uses the same wrapper for a malformed `--ws-portrange` flag value.

**What to do:** Correct the key that the message names to a value it accepts. The message states the accepted values or range.

**Exit code:** 1, and 2 when the value came from `--ws-portrange`.

### `{key} is empty; give a path, or remove the key for the default`

A path-valued key in the configuration file holds an empty string. `{key}` is the key, for example `[hep] tls_ca`, `[api] tls_cert`, `[journal] dir`, `[crash] report_dir` or `[vcon_forward] ca`. An empty path names no file. The printed line starts with `invalid config value: `.

**What to do:** Write the path between the quotes, or delete the key so sipnab uses its default.

**Exit code:** 1.

### `` `${{{name}}}` is not a variable name: expected an ASCII letter or `_` followed by letters, digits or `_`. Shell default-value syntax is not supported ``

A string in the config file holds `${`, some text and `}`, and the text between the braces is not an environment-variable name. A config file `c.toml` with `node_name = "${HOME:-x}"` under `[capture]` stops the run with this line:

```text
2026-10-18T15:29:43.704481Z ERROR sipnab::app::bootstrap: invalid config value: c.toml: capture.node_name: `${HOME:-x}` is not a variable name: expected an ASCII letter or `_` followed by letters, digits or `_`. Shell default-value syntax is not supported
```

- `{name}` is the text between the braces.
- A name must start with an ASCII letter or `_`. It continues with letters, digits or `_`.
- sipnab refuses shell forms such as `${VAR:-default}`, and an empty `${}`.
- The full line reads `invalid config value: <file>: <dotted.key>:` followed by this text. It names the file and the setting.

**What to do:** Write `${NAME}` with a plain variable name. To keep a literal `$` in a value, write `$$`.

**Exit code:** 1.

### `` `${{{name}}}` is not set in the environment. An unset variable is refused rather than expanded to nothing, because an empty expansion inside a path names a real directory that is not the one intended ``

A string in the config file uses `${NAME}`, and the environment sipnab runs in has no variable of that name. `{name}` is the variable. sipnab refuses the value rather than substituting an empty string. The full line reads `invalid config value: <file>: <dotted.key>:` followed by this text, naming the file and the setting.

**What to do:** Set the variable in the environment that starts sipnab, or replace `${NAME}` with the literal value. To keep a literal `$`, write `$$`.

**Exit code:** 1.

### `[keybindings] {key} = {v:?} is not a key: give one character, a function key (F1-F12) or a named key (Enter, Esc, Tab, Space, Backspace)`

A `[keybindings]` value is not a key the terminal UI can read.

- `{key}` is the action: `quit`, `help`, `filter`, `save`, `search`, `settings`, `pause`, `autoscroll`, `extended_flow`, `clear_calls` or `column_selector`.
- `{v:?}` is the value in the file.
- sipnab accepts one character, `F1` to `F12`, or `Enter`, `Esc`, `Tab`, `Space` or `Backspace` (also in lowercase).
- sipnab checks this section only in builds that include the terminal UI.
- The printed line starts with `invalid config value: `.

**What to do:** Set the named action to one character, a function key such as `F5`, or one of the named keys. Or remove the line.

**Exit code:** 1.

### `[limits] api_max_rows must be > 0 (0 would answer every list request with an empty page)`

`[limits] api_max_rows` is the most rows one list response from the REST API may return. A value of 0 would answer every list request with an empty page, so sipnab refuses it. The printed line starts with `invalid config value: `.

**What to do:** Set a whole number of 1 or more, for example the default `1000`, or remove the key.

**Exit code:** 1.

### `[limits] api_rate_limit_per_peer must be at most {} (0 disables the cap), got {v}`

`[limits] api_rate_limit_per_peer` is how many REST API requests one client IP address may make per second. The value is larger than the highest number sipnab can hold for this setting, which `{}` shows (4294967295). `{v}` is the value in the file. A value of 0 turns the cap off. The printed line starts with `invalid config value: `.

**What to do:** Set a number from 0 to 4294967295, or remove the key for the default of 100.

**Exit code:** 1.

### `[limits] exec_queue_depth must be > 0 (it bounds child processes, so there is no unlimited setting; to run no hooks, drop --on-dialog-exec and --on-quality-exec)`

`[limits] exec_queue_depth` is how many hook commands from `--on-dialog-exec` and `--on-quality-exec` may run at once before sipnab drops events. A value of 0 has no meaning here, because the setting bounds the number of child processes and has no unlimited value. The printed line starts with `invalid config value: `.

**What to do:** Set a whole number of 1 or more, for example the default `100`. To run no hooks, leave out `--on-dialog-exec` and `--on-quality-exec`.

**Exit code:** 1.

### `[limits] idle_compact_after_secs must be > 0 (0 would compact dialogs that are still active; to keep more of the ladder, raise this or raise keep_messages_per_idle_dialog)`

`[limits] idle_compact_after_secs` is how many seconds a dialog must stay silent before sipnab compacts it. A dialog is one SIP conversation, such as a call. Compacting keeps only some of its messages.

- A value of 0 would compact dialogs that are still active.
- The printed line starts with `invalid config value: `.

**What to do:** Set a whole number of 1 or more, for example the default `600`. To keep more of each idle dialog, raise this value or `keep_messages_per_idle_dialog`.

**Exit code:** 1.

### `[limits] lint_max_per_rule must be > 0 (0 would print every repeat of one rule and bury the others)`

`[limits] lint_max_per_rule` is how many findings one lint rule may raise for one dialog. A value of 0 would remove the cap, so one repeating rule could fill the output, and sipnab refuses it. The printed line starts with `invalid config value: `.

**What to do:** Set a whole number of 1 or more, for example the default `25`, or remove the key.

**Exit code:** 1.

### `[limits] max_audio_bytes must be >= {} (1 MiB), got {v}; to keep no audio at all, leave --retain-audio off`

`[limits] max_audio_bytes` bounds the audio that `--retain-audio` keeps across every call.

- The value you set, `{v}`, is below the minimum, `{}`, 1048576 bytes.
- sipnab refuses it rather than read it as "keep nothing". A budget smaller than one large frame would release every frame it received.
- The printed line starts with `invalid config value: `.

**What to do:** Set `max_audio_bytes` to 1048576 or more, or remove the key for the default. To keep no audio, leave `--retain-audio` off.

**Exit code:** 1.

### `[limits] max_capture_sources must be >= 1 (it must hold every capture source a run reads: input files, devices, HEP senders, traced processes)`

`[limits] max_capture_sources` is how many capture sources sipnab remembers by name: each input file, capture device, HEP sender and traced process. A value of 0 leaves no room for even one source. The printed line starts with `invalid config value: `.

**What to do:** Set a whole number of 1 or more, for example the default `65536`, or remove the key.

**Exit code:** 1.

### `[limits] max_header_line must be >= 256`

`[limits] max_header_line` is the most bytes sipnab accepts in one SIP header line. The value in the file is below 256, the smallest value sipnab accepts. The printed line starts with `invalid config value: `.

**What to do:** Set a value of 256 or more, for example the default `8192`, or remove the key.

**Exit code:** 1.

### `[limits] max_lost_sequences must be > 0 (0 would retain no losses, so the loss map and the burst/gap analysis would report a lossless call)`

`[limits] max_lost_sequences` is how many lost RTP sequence numbers sipnab keeps for each media stream.

- RTP (Real-time Transport Protocol) carries the audio.
- The packet-loss map and the burst and gap analysis read these numbers.
- A value of 0 would keep none, so every call would look lossless.
- The printed line starts with `invalid config value: `.

**What to do:** Set a whole number of 1 or more, for example the default `1000`, or remove the key.

**Exit code:** 1.

### `[limits] max_tcp_buffer must be >= {} (a smaller ceiling cannot hold one SIP header line, so every SIP/TCP message would be flushed mid-message and reported malformed), got {v}`

`[limits] max_tcp_buffer` is how many bytes sipnab may buffer for one direction of a SIP over TCP connection, before it flushes the buffer.

- `{}` is the smallest value accepted, 8192. That is the longest single header line the parser accepts.
- `{v}` is the value in the file.
- A smaller buffer cannot hold one header line. So sipnab would report every SIP over TCP message as malformed.
- The printed line starts with `invalid config value: `.

**What to do:** Set a value of 8192 or more, for example the default `65536`, or remove the key.

**Exit code:** 1.

### `[limits] max_tracked_peers must be >= {} (a map of one turns the per-peer cap into a global lock: the first peer to send in a window takes the only slot and every other peer is refused for the rest of it), got {v}`

`[limits] max_tracked_peers` is how many different peers one rate-limit window may track. Peers are HEP senders and MCP callers.

- `{}` is the smallest value accepted, 2.
- `{v}` is the value in the file.
- With room for one peer, the first peer to send in a window would take the only slot. sipnab would then refuse every other peer for the rest of that window.
- The printed line starts with `invalid config value: `.

**What to do:** Set a value of 2 or more, for example the default `4096`. Set at least the number of peers that send to this sipnab.

**Exit code:** 1.

### `[limits] mcp_max_body_bytes must be > 0 (0 would answer every body question with a truncation marker and no body)`

`[limits] mcp_max_body_bytes` is how many bytes of SIP body or matched text one MCP response may carry. MCP (Model Context Protocol) is the interface AI assistants use to query sipnab. A value of 0 would replace every body with a truncation marker. The printed line starts with `invalid config value: `.

**What to do:** Set a whole number of 1 or more, for example the default `4096`, or remove the key.

**Exit code:** 1.

### `[limits] mcp_max_findings must be > 0 (0 refuses every write; to accept no findings, drop --mcp-allow-save-findings)`

`[limits] mcp_max_findings` is how many findings the MCP `save_findings` tool accepts before it refuses more. A value of 0 would refuse every write. The printed line starts with `invalid config value: `.

**What to do:** Set a whole number of 1 or more, for example the default `1000`. To accept no findings, leave out `--mcp-allow-save-findings`.

**Exit code:** 1.

### `[limits] mcp_max_wait_seconds must be > 0 (0 would make await_condition answer before it looked, which is a poll spelled expensively)`

`[limits] mcp_max_wait_seconds` is the longest, in seconds, that one MCP `await_condition` call may wait. A value of 0 would make the call answer before it checked anything. The printed line starts with `invalid config value: `.

**What to do:** Set a whole number of 1 or more, for example the default `60`, or remove the key.

**Exit code:** 1.

### `[limits] metrics_max_conn must be > 0 (0 refuses every scrape and the /metrics endpoint answers 503 forever; to serve no metrics, drop --metrics)`

`[limits] metrics_max_conn` is how many scrapes the `/metrics` endpoint serves at once, before it answers `503`. A scrape is a request from a monitoring system such as Prometheus.

- A value of 0 would turn every scrape away.
- The printed line starts with `invalid config value: `.

**What to do:** Set a whole number of 1 or more, for example the default `16`. To serve no metrics, leave out `--metrics`.

**Exit code:** 1.

### `[limits] {key} must be 1-{max} ({why}), got {v}`

A `[limits]` setting for the MCP `find_in_captures` sweep is 0 or above its maximum. The sweep is a search across saved capture files.

- `{key}` and `{max}` are one of:
  - `mcp_sweep_max_files` up to 4294967295;
  - `mcp_sweep_deadline_ms` up to 43200000;
  - `mcp_sweep_max_running` up to 64;
  - `mcp_sweep_max_held_results` up to 256;
  - `mcp_sweep_result_retention_secs` up to 43200.
- `{why}` says what each end of the range protects.
- `{v}` is the value in the file.
- The printed line starts with `invalid config value: `.

**What to do:** Set the named key to a whole number from 1 to the maximum shown, or remove the key.

**Exit code:** 1.

### `[limits] quality_interval_secs ({secs}) must be between {} and {} (0 would snapshot on every packet; a period wider than the retained hour leaves a trend of one entry)`

`[limits] quality_interval_secs` is how often, in seconds, sipnab records a quality snapshot for each media stream. `{secs}` is the value in the file, and the two `{}` are the accepted range, 1 and 300. The printed line starts with `invalid config value: `.

**What to do:** Set a whole number from 1 to 300, or remove the key.

**Exit code:** 1.

### `[limits] reassembly_ttl_secs must be > 0 (0 evicts every partial on the next sweep and reports both halves as malformed; to turn reassembly off, use --no-reassembly)`

`[limits] reassembly_ttl_secs` is how many seconds sipnab holds an incomplete IP datagram or a half-read TCP stream before a sweep discards it. A value of 0 would discard every partial message on the next sweep, and sipnab would report both halves as malformed. The printed line starts with `invalid config value: `.

**What to do:** Set a whole number of 1 or more, for example the default `30`. To turn reassembly off, use `--no-reassembly`.

**Exit code:** 1.

### `[media.codec_ie] {codec} must be >= 0 and < {} (at or above that the E-model's loss term goes negative and MORE packet loss would RAISE the score), got {ie}`

A `[media.codec_ie]` entry is out of range.

- Each entry sets the equipment impairment factor (`Ie`) for one codec. That factor is the E-model's measure of how much a codec degrades voice quality.
- sipnab uses it in its MOS (mean opinion score) estimate.
- `{codec}` is the codec name.
- `{}` is the upper limit 95.
- `{ie}` is the value in the file.
- At 95 or above, more packet loss would raise the score.
- The printed line starts with `invalid config value: `.

**What to do:** Set the codec's value to a number of 0 or more and below 95, or remove the entry.

**Exit code:** 1.

### `[media] listening_context must be "monotic" or "diotic", got "{lc}"`

`[media] listening_context` says how the far end listened to wideband (AMR-WB) audio, which changes the quality score. sipnab accepts `monotic` (a handset or one-ear headset) or `diotic` (a stereo headset or speakerphone), in any case. `{lc}` is the value in the file. The printed line starts with `invalid config value: `.

**What to do:** Set `listening_context` to `monotic` or `diotic`, or remove the key for the default `monotic`.

**Exit code:** 1.

### `[media] one_way_delay_ms must be a finite number of 0 or more, got {ms}`

`[media] one_way_delay_ms` is the one-way network delay, in milliseconds, that sipnab uses for the quality score on this path. The value must be 0 or more and a finite number (not infinity or NaN, not-a-number). `{ms}` is the value in the file. The printed line starts with `invalid config value: `.

**What to do:** Set a number of 0 or more, or remove the key.

**Exit code:** 1.

### `{key} must be > 0`

A count in the configuration file is 0.

- `{key}` is the key. It is one of:
  - `[capture] snaplen`;
  - `[capture] buffer`;
  - the `[limits]` keys `dialog_limit`, `mcp_max_rows`, `max_streams`, `max_reassembly`, `max_headers_per_message`, `max_messages_per_dialog`, `max_audio_frames`, `keep_messages_per_idle_dialog`, `max_groups`, `max_grouped_messages`, `max_metadata_file_bytes` or `max_gunzip_bytes`.
- The matching command-line flags refuse 0 too.
- The printed line starts with `invalid config value: `.

**What to do:** Set the named key to a whole number of 1 or more, or remove it for the default.

**Exit code:** 1.

### `[names] dns_cache_entries must be > 0 (0 evicts on every insert, holding about one entry)`

`[names] dns_cache_entries` is how many reverse-DNS results (names looked up from IP addresses) sipnab keeps at once. A value of 0 would hold about one entry. The printed line starts with `invalid config value: `.

**What to do:** Set a whole number of 1 or more, for example the default `4096`, or remove the key.

**Exit code:** 1.

### `[names] hosts_file {hf:?} cannot be read: {e}`

sipnab could not open the file named by `[names] hosts_file`, a file of IP address to name lines in `/etc/hosts` format. `{hf:?}` is the path, in double quotes, and `{e}` is the operating system's reason, or `is a directory` when the path names a directory. The printed line starts with `invalid config value: `.

**What to do:** Point `hosts_file` at an existing file that the user running sipnab can read, or remove the key.

**Exit code:** 1.

### `[names] is not a table`

In the terminal UI you named an address with `[names] persist_to_config` on. sipnab tried to save the name in the `[names.manual]` table of the configuration file.

- The file defines `names` as a plain value instead of a `[names]` table (section). So sipnab writes nothing to it.
- The status line shows this text after `Named, but couldn't update` and the file path.

**What to do:** Edit the configuration file so `names` is a `[names]` section, then name the address again.

**Exit code:** None. sipnab shows the error on the terminal UI status line, and the run continues.

### `[names.manual] key {ip:?} is not an IP address`

A key in the `[names.manual]` table, which maps IP addresses to display names, is not an IP address. `{ip:?}` is the key, in double quotes. The printed line starts with `invalid config value: `.

**What to do:** Make each key a single IPv4 or IPv6 address in quotes, for example `"192.0.2.1" = "pbx"`, or remove the entry.

**Exit code:** 1.

### `[names.manual] name {name:?} for {ip} is not a valid name`

A name in the `[names.manual]` table is empty, longer than 253 bytes, or contains a control character. `{name:?}` is the name, in double quotes, and `{ip}` is the address it belongs to. The printed line starts with `invalid config value: `.

**What to do:** Give the address a name of 1 to 253 bytes with no control characters such as tabs or newlines.

**Exit code:** 1.

### `not saved: the settings in use come from {SYSTEM_CONFIG_PATH}, and a user file would hide every setting in it. Copy it to ~/.config/sipnab/sipnab.toml to save from the terminal UI`

The terminal UI shows this on its status line in this case:

- You ask for a save: the F10 column layout, or name edits with `[names] persist_to_config`.
- The settings in use came from the system file `/etc/sipnab/sipnab.toml`.

sipnab does not write a user file. sipnab reads a user file before the system file, so the user file would hide every setting in it. sipnab saves nothing.

**What to do:**

- Copy `/etc/sipnab/sipnab.toml` to your user config file. That is `~/.config/sipnab/sipnab.toml`, or `$XDG_CONFIG_HOME/sipnab/sipnab.toml` when that variable holds an absolute path.
- Start sipnab so it loads the copy (or with `--config` naming the copy).
- Save again.

**Exit code:** None. This is a status-line message, and the run continues.

### `{e}; off-hours fraud detection is OFF for this run`

Fraud detection is on, but the business-hours window (`--business-hours` or `[security] business_hours`) did not parse.

- sipnab turns the off-hours check off for this run. The other fraud checks still run.
- `{e}` is the parse error.
- The code notes that startup validation refuses a bad value first. So this line appears only when that validation did not run.

**What to do:** Give the window as `START-END`, in whole hours 0-23, with different start and end.

- For example, `8-18`.
- Or `22-6` for an overnight window.

**Exit code:** None. sipnab logs the error, and the run continues.

### `Reading {}. Also present and NOT read: {}. sipnab reads only the first config file it finds; merge them or remove the ones you do not want.`

More than one default config file exists. sipnab read the first one named and none of the others listed after it.

**What to do:** Merge the files into one, or remove the ones you do not want.

**Exit code:** None. This is a warning, and the run continues.

### `read {}: {e}. Refusing to save, because writing what was merged into an empty file would replace the existing configuration`

While saving from the terminal UI, sipnab could not read the existing configuration file.

- `{}` is the file path.
- `{e}` is the operating system's reason, such as permission denied, or a file that is not UTF-8 text.
- sipnab stops instead of saving. Writing into an empty copy would erase your other settings.
- A missing file is not an error: sipnab creates it.

**What to do:** Make the file readable by the user running sipnab, or fix its contents, then save again.

**Exit code:** None. sipnab shows the error on the terminal UI status line, and the run continues.

### `[security] business_hours {reason}`

`[security] business_hours` is not a usable working-hours window. `{reason}` says why. There are two cases:

- The value is not two whole hours from 0 to 23 joined by `-`. The reason then quotes the value.
- The start and end hours are the same. That would make every call off-hours.

The hours are UTC. The printed line starts with `invalid config value: `.

**What to do:** Write `business_hours` as `"START-END"`, in whole hours from 0 to 23, with different start and end.

- For example, `"8-18"`.
- Or `"22-6"` for a window that crosses midnight.

**Exit code:** 1.

### `[security] fraud_destination {bad:?} is not a destination sipnab can match: give ISO 3166-1 alpha-2 codes the dial plan labels (NANP for +1 numbers), comma-separated`

One entry in the comma-separated `[security] fraud_destination` list is not a destination label sipnab knows.

- `{bad:?}` is the first such entry, in double quotes.
- Labels are the two-letter ISO 3166-1 alpha-2 country codes from sipnab's dial plan.
- Numbers that start with +1 carry the label `NANP` (North American Numbering Plan).
- The printed line starts with `invalid config value: `.

**What to do:** Replace the named entry with a country code from the dial plan, such as `GB`. Use `NANP` for any +1 destination. Separate entries with commas.

**Exit code:** 1.

### `[security] hep_hmac_window_secs must be 1-{MAX_HEP_HMAC_WINDOW_SECS} (the window is how long a captured packet stays replayable and how many nonces the receiver must remember; a sender more than {MAX_HEP_HMAC_WINDOW_SECS}s adrift has no working time daemon, which is what to fix), got {v}`

`[security] hep_hmac_window_secs` is how many seconds a HEP packet's signed timestamp may differ from this machine's clock. It applies when `--hep-auth-mode hmac` is on. HEP is the protocol capture agents use to send packets to a collector.

- The value is 0 or above 300, the maximum that `{MAX_HEP_HMAC_WINDOW_SECS}` shows.
- `{v}` is the value in the file.
- A wider window keeps a captured packet replayable for longer.
- The printed line starts with `invalid config value: `.

**What to do:** Set a whole number from 1 to 300, or remove the key for the default of 30. If a sender's clock is off by more than that, fix the time synchronization (for example NTP) on that sender.

**Exit code:** 1.

### `[security] kill_rate_limit must be > 0 (it bounds responses sipnab puts on the wire, so there is no unlimited setting; to send none, drop --kill-scanner and -K)`

`[security] kill_rate_limit` is how many scanner-kill responses per second sipnab may send on the network. A value of 0 has no meaning here, because the setting bounds packets sipnab sends and has no unlimited value. The printed line starts with `invalid config value: `.

**What to do:** Set a whole number of 1 or more, for example the default `10`. To send no responses, leave out `--kill-scanner` and `-K`.

**Exit code:** 1.

### `[hep] {key} must be 1-{max}, got {v}`

A HEP sender setting in `[hep]` is outside the range its flag accepts.

- `{key}` is `send_queue_mib` (1 to 4096, `--hep-send-queue`) or `send_timeout_secs` (1 to 300, `--hep-send-timeout`).
- `{max}` is the top of that range, and `{v}` is the value in the file.

The printed line starts with `invalid config value: `.

**What to do:** Set a value in the range, or remove the key to use the default (64 MiB, 3 seconds).

**Exit code:** 1.

### `[security] kill_response must be 100-699, got {code}`

`[security] kill_response` is the SIP status code sipnab sends in a scanner-kill response. SIP status codes run from 100 to 699, and `{code}` is the value in the file. The printed line starts with `invalid config value: `.

**What to do:** Set a code from 100 to 699, or remove the key.

**Exit code:** 1.

### `[security] {key} must be > 0`

A fraud-detection or scanner-detection count, window or factor in `[security]` is 0.

- `{key}` is one of `fraud_short_call_secs`, `fraud_sequential_calls`, `scanner_enumeration_targets`, `fraud_volume_window_secs`, `fraud_wangiri_window_secs`, `scanner_window_secs`, `scanner_answer_grace_ms`, `fraud_wangiri_calls`, `fraud_volume_multiplier`, `fraud_volume_min_calls`, `scanner_behavioral_probes`, `scanner_rejected_probes`, `scanner_unanswered_probes` or `scanner_established_factor`.
- A value of 0 makes a detector report everything or nothing.
- The printed line starts with `invalid config value: `.

**What to do:** Set the named key to a whole number of 1 or more, or remove it for the default.

**Exit code:** 1.

### `[security] reg_flood_threshold must be > 0 (0 would report every REGISTER as a flood; to switch the detector off, drop --reg-flood)`

`[security] reg_flood_threshold` is how many challenged REGISTER failures from one source inside one window sipnab counts before it reports a registration flood. A value of 0 would report every REGISTER as a flood. The printed line starts with `invalid config value: `.

**What to do:** Set a whole number of 1 or more, for example the default `50`. To turn the detector off, leave out `--reg-flood`.

**Exit code:** 1.

### `[security] reg_flood_transaction_timeout_ms must be {MIN_TRANSACTION_TIMEOUT_MS}-{MAX_TRANSACTION_TIMEOUT_MS} (milliseconds; RFC 3261 Timer F is 64*T1, 32000 at the default T1 of 500 ms), got {v}`

`[security] reg_flood_transaction_timeout_ms` is how long, in milliseconds, a REGISTER that carried credentials waits for the challenge that answers it.

- The accepted range is 1000 to 600000. The two placeholders show it.
- `{v}` is the value in the file.
- [RFC 3261](https://www.rfc-editor.org/rfc/rfc3261.html) Timer F is 64 times T1. That is 32000 at the default T1 of 500 ms.
- The printed line starts with `invalid config value: `.

**What to do:** Set a whole number from 1000 to 600000, or remove the key for the default of 32000.

**Exit code:** 1.

### `[security] reg_flood_window_secs must be 1-{MAX_WINDOW_SECS} (seconds of capture time one failure count spans), got {v}`

`[security] reg_flood_window_secs` is how many seconds of capture time one registration-flood count spans. The accepted range is 1 to 3600, which `{MAX_WINDOW_SECS}` shows, and `{v}` is the value in the file. The printed line starts with `invalid config value: `.

**What to do:** Set a whole number from 1 to 3600, or remove the key for the default of 1.

**Exit code:** 1.

### `[sip] active_idle_window_secs must be > 0 (0 leaves the active-dialog and active-call gauges permanently at zero, which reads as a quiet trunk rather than as a setting)`

`[sip] active_idle_window_secs` is how many seconds a dialog may go without a message and still count toward two gauges. The gauges are the active-dialog and active-call counters in the metrics output.

- A value of 0 would keep both gauges at zero.
- The printed line starts with `invalid config value: `.

**What to do:** Set a whole number of 1 or more, for example the default `3600`, or remove the key.

**Exit code:** 1.

### `[sip] leg_correlation_window_ms must be > 0 (0 still correlates legs created in the same millisecond; to ignore the guess, read the strategy each correlation is reported under)`

`[sip] leg_correlation_window_ms` is how many milliseconds apart two legs of one call may start for sipnab to still join them on timing alone. sipnab refuses 0 because it does not turn timing correlation off: legs created in the same millisecond still correlate. The printed line starts with `invalid config value: `.

**What to do:** Set a whole number of 1 or more, for example the default `2000`, or remove the key. To disregard timing-based joins, check the strategy that sipnab reports with each correlation.

**Exit code:** 1.

### `sipnabrc is not valid TOML: {e}`

While saving from the terminal UI, sipnab found that the existing configuration file is not valid TOML (the configuration file format).

- So it cannot update one section and keep the rest.
- `{e}` is the TOML parser's description of the problem and where it is.
- sipnab writes nothing.

**What to do:** Fix the TOML syntax at the place the error names, then save again.

**Exit code:** None. sipnab shows the error on the terminal UI status line, and the run continues.

### `[theme] {key} = {v:?} is not a color: give a name (red, dark_gray, reset, ...) or #rrggbb`

A `[theme]` color is not one sipnab can read.

- `{key}` is the slot: `background`, `foreground`, `highlight`, `header`, `selected`, `accent`, `good`, `warning`, `bad`, `muted`, `border` or `status_bg`.
- `{v:?}` is the value in the file.
- sipnab accepts, in any case:
  - `black`, `white`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `gray`, `dark_gray`, `reset` (and a few alternative spellings);
  - or `#` and six hexadecimal digits.
- sipnab checks this section only in builds that include the terminal UI.
- The printed line starts with `invalid config value: `.

**What to do:** Set the named slot to one of the color names, or to a value such as `#1e90ff`. Or remove the line.

**Exit code:** 1.

### `Unknown color value: {s:?}`

A `[theme]` color in the config file is not a color sipnab knows.

- It is not a known color name: black, white, red, green, yellow, blue, magenta, cyan, gray or grey, `dark_gray` and its spellings, reset or default.
- It is not a `#` value of 7 characters.
- `{s:?}` is the value as written.
- sipnab logs this warning while it checks the config at startup. The refusal `invalid config value: [theme] <key> = "<value>" is not a color:` follows it.
- sipnab refuses a 7-character `#` value with non-hex digits without this warning line.

**What to do:** Use one of the listed names or a `#rrggbb` hex value for that `[theme]` key.

**Exit code:** 1, from the refusal that follows this line.

### `Unknown config key: {key}`

The config file contains a key or a section that sipnab does not recognize. `{key}` is the name: `name` for a top-level entry, and `section.key` inside a known section. sipnab ignores it and keeps running, so the setting has no effect. For an unknown section, sipnab reports the section name and does not list the keys inside it.

**What to do:** Correct the spelling, move the key into the section it belongs to, or delete it.

**Exit code:** None. This is a warning, and the run continues.

### `Unknown keybinding value: {s:?}`

A `[keybindings]` value in the config file is not a key the terminal UI can bind.

- `{s:?}` is the value as written.
- sipnab accepts one character, `F1` to `F12`, or a named key (Esc, Space, Enter, Tab, Backspace and their listed spellings).
- sipnab logs this warning while it checks the config at startup. The refusal `invalid config value: [keybindings] <key> = "<value>" is not a key:` follows it.
- sipnab refuses a value that starts with `F` or `f` but is not `F1` to `F12`. It does so without this warning line.

**What to do:** For that `[keybindings]` entry, use one character, a function key from `F1` to `F12`, or one of the named keys.

**Exit code:** 1, from the refusal that follows this line.

### `` unterminated `${{` in {input:?} ``

A string in the config file contains `${` with no closing `}`. `{input:?}` is the whole string as written. The full line names the file and the setting. A config file `a.toml` with `node_name = "${HOME"` under `[capture]` stops the run with this line:

```text
2026-10-18T15:29:43.565059Z ERROR sipnab::app::bootstrap: invalid config value: a.toml: capture.node_name: unterminated `${` in "${HOME"
```

**What to do:** Close the variable reference (`${NAME}`), or write `$$` where you mean a literal `$`.

**Exit code:** 1.

### `[vcon_fetch] {}: {e}`

A whole-number `[vcon_fetch]` key is out of range. `{}` is the key (`timeout`, `max_response_head` or `max_size`), and `{e}` reads `N is out of range: give a whole number from MIN to MAX` with the value and the limits. `timeout` accepts 1 to 600 and the other two accept 1 to 4294967295. The printed line starts with `invalid config value: `.

**What to do:** Set the named key to a whole number in the range shown, or remove it.

**Exit code:** 1.

### `[vcon_fetch] signer_sha256: {e}`

`[vcon_fetch] signer_sha256` is not a SHA-256 fingerprint.

- `{e}` reads `"VALUE": a SHA-256 fingerprint is 64 hex digits, plain or in colon-separated pairs`, with the value from the file.
- The printed line starts with `invalid config value: `.

**What to do:** Set `signer_sha256` to the signing certificate's fingerprint, for example the output of `openssl x509 -noout -fingerprint -sha256 -in signing.crt`, or remove the key.

**Exit code:** 1.

### `[vcon_input] signer_sha256: {e}`

`[vcon_input] signer_sha256` is not a SHA-256 fingerprint.

- `{e}` reads `"VALUE": a SHA-256 fingerprint is 64 hex digits, plain or in colon-separated pairs`, with the value from the file.
- The printed line starts with `invalid config value: `.

**What to do:** Set `signer_sha256` to the signing certificate's fingerprint, for example the output of `openssl x509 -noout -fingerprint -sha256 -in signing.crt`, or remove the key.

**Exit code:** 1.

### `[vcon_fetch] kind: {name:?} is not one of {}`

`[vcon_fetch] kind` names a vCon store type sipnab does not know. A vCon is a standard JSON container for a conversation. `{name:?}` is the value in the file, and `{}` lists the accepted names: `generic`, `vcon-store`, `conserver` and `vcon-mcp`. The printed line starts with `invalid config value: `.

**What to do:** Set `kind` to one of the listed names, or remove the key.

**Exit code:** 1.

### `[vcon] encrypt_to is an empty list: name at least one recipient certificate, or remove the key`

`[vcon] encrypt_to` is `[]`. Nobody could open a container encrypted to no recipient, so sipnab refuses the list rather than write one.

- The printed line starts with `invalid config value: `.

**What to do:** List at least one recipient certificate, or remove the key so that no rule inherits it.

**Exit code:** 1.

### `[vcon] compress: {value:?} is not one of {}`

The `[vcon]` section's `compress` key names a compression sipnab does not write.

- `{value:?}` is the value in the file.
- `{}` lists the accepted values: `none` and `gzip`.
- The printed line starts with `invalid config value: `.

**What to do:** Set `compress` to `none` or `gzip`, or remove the key.

**Exit code:** 1.

### `[vcon] uuid_domain: {value:?} {why}`

The `[vcon]` section's `uuid_domain` key is not a fully qualified host name.

- `{value:?}` is the value in the file.
- `{why}` says which rule it breaks: it is empty, it has one label, a label is empty or longer than `MAX_UUID_DOMAIN_LABEL` (63) characters, the name is longer than `MAX_UUID_DOMAIN_NAME` (253) characters, it has a character other than an ASCII letter, a digit, a hyphen or a dot, a label starts or ends with a hyphen, or it is an IPv4 address.
- The printed line starts with `invalid config value: `.

**What to do:** Set `uuid_domain` to a host name such as `node1.pbx.example.com`, writing an internationalized name in its `xn--` form, or remove the key. See [The uuid under a domain](vcon.md#the-uuid-under-a-domain).

**Exit code:** 1.

### `[vcon_forward] {}: {e}`

A whole-number `[vcon_forward]` key is out of range.

- `{}` is the key.
- `{e}` reads `N is out of range: give a whole number from MIN to MAX`, with the value and the limits.
- The ranges are:
  - `interval` accepts 1 to 3600;
  - `timeout` 1 to 600;
  - `backoff_first`, `backoff_cap`, `max_response_head` and `max_error_body` 1 to 4294967295.
- The printed line starts with `invalid config value: `.

**What to do:** Set the named key to a whole number in the range shown, or remove it.

**Exit code:** 1.

### `[vcon_forward] content_type: {e}`

`[vcon_forward] content_type` names a media type the forwarder does not send for a JSON container.

- `{e}` reads `"VALUE" is not one of application/json, application/vcon+json, application/vcon`, with the value from the file.
- A gzip format container always goes as `application/vcon+gzip`, so that value is not accepted here.
- The printed line starts with `invalid config value: `.

**What to do:** Set `content_type` to one of the listed types, or remove the key for `application/json`.

**Exit code:** 1.

### `{value:?} is not one of {}`

The media type given to `--vcon-forward-content-type`, or to `[vcon_forward] content_type`, is not one the forwarder sends for a JSON container.

- `{value:?}` is the value given, and `{}` lists the accepted types: `application/json`, `application/vcon+json` and `application/vcon`.
- From the flag, the line starts with `error: invalid value` and names the flag, and sipnab exits `2`.
- From the config file, the line starts with `invalid config value: [vcon_forward] content_type: `, and sipnab exits `1`.

**What to do:** Give one of the listed types, or leave the setting out for `application/json`. A gzip format container always goes as `application/vcon+gzip`.

**Exit code:** 2 from the flag, 1 from the config file.

### `[vcon_forward] kind: {name:?} is not one of {}`

`[vcon_forward] kind` names a vCon store type the forwarder does not know. A vCon is a standard JSON container for a conversation. `{name:?}` is the value in the file, and `{}` lists the accepted names: `generic`, `vcon-store` and `conserver`. The printed line starts with `invalid config value: `.

**What to do:** Set `kind` to one of the listed names, or remove the key.

**Exit code:** 1.

### `write {}: {e}`

sipnab could not write the configuration file while saving from the terminal UI. `{}` is the file path and `{e}` is the operating system's reason. sipnab writes to a temporary file in the same folder and then renames it, so the existing file stays unchanged.

**What to do:** Give the user running sipnab permission to write in the folder that holds the file. Check that the disk has free space. Then save again.

**Exit code:** None. sipnab shows the error on the terminal UI status line, and the run continues.

### `{display}: {e}`

A `${NAME}` reference to an environment variable, in a configuration file string, has no value sipnab can use.

- `{display}` is the configuration file path.
- `{e}` is the dotted key path of the setting (for example `capture.device`, or `vcon_forward.ca`), followed by `: ` and the reason. The reason is one of these:
  - the variable is not set;
  - the `${` has no closing `}`;
  - the name is not a valid variable name.
- sipnab refuses an unset variable instead of replacing it with nothing.
- The printed line starts with `invalid config value: `.

**What to do:** Do one of these:

- Set the named variable in the environment that starts sipnab.
- Close the `${`.
- Correct the name to letters, digits and `_`, starting with a letter or `_`.

Write `$$` for a literal `$`.

**Exit code:** 1.

### `[capture] ws_ports: {e}`

The SIP over WebSocket port range that `[capture] ws_ports` in the configuration file gives is not usable.

- `{e}` says what is wrong:
  - the value is not two ports joined by `-`;
  - one side is not a port number from 0 to 65535;
  - the start is higher than the end.
- The printed line starts with `invalid config value: `.
- `--ws-portrange` on the command line replaces the key. sipnab does not read the key when you give the flag.

**What to do:** Give the range as `START-END` with the lower port first, for example `8080-8443`. Or remove the key for the shipped ports.

**Exit code:** 1.

### `[pbx] addresses: '{entry}' is not an IP address or a CIDR range: {e}`

An entry in `[pbx] addresses` is neither an IP address nor a CIDR range. `{entry}` is the entry and `{e}` is the parser's reason. `[pbx] addresses` lists the PBX's own addresses, which the filter field `side` compares against.

**What to do:** Write each entry as an address (`192.0.2.10`) or a range (`198.51.100.0/24`).

**Exit code:** 1.

### `[[vcon.rule]] name '{name}' is not usable: a name is 1 to {} ASCII letters, digits, '-' or '_', starting with a letter or digit`

A [`[[vcon.rule]]`](vcon.md#write-calls-by-rule) has a `name` sipnab cannot use. `{name}` is the name, and `{}` is the longest a name may be.

**What to do:** Use 1 to 64 ASCII letters, digits, `-` or `_`, starting with a letter or digit.

**Exit code:** 1.

### `[[vcon.rule]] name '{name}' is used by two rules; each rule needs its own`

Two [`[[vcon.rule]]`](vcon.md#write-calls-by-rule) entries have the same `name`. A rule's name picks its spool on REST and MCP, so each must be unique.

**What to do:** Rename one of the rules.

**Exit code:** 1.

### `[[vcon.rule]] '{name}' has no dir: say where its containers go`

The [`[[vcon.rule]]`](vcon.md#write-calls-by-rule) named `{name}` has no `dir`, so its containers would go nowhere.

**What to do:** Add `dir = "/path/to/spool"` to the rule.

**Exit code:** 1.

### `[[vcon.rule]] '{name}' has {why}`

A key of the [`[[vcon.rule]]`](vcon.md#write-calls-by-rule) named `{name}` has a value sipnab does not take. `{why}` names the key, the value and the values it takes: `audio` takes `inline`, `url` or `omit`, `audio_format` takes `wav` or `opus`, and `grouping` takes `leg` or `call`.

- A sipnab built without the `opus` Cargo feature refuses `audio_format = "opus"`, and `{why}` names the feature. The static musl builds do not have it.

**What to do:** Set the key to one of the values `{why}` lists.

**Exit code:** 1.

### `audio = '{other}'; use 'inline', 'url' or 'omit'`

The reason inside `[[vcon.rule]] '{name}' has {why}` for an `audio` value other than `inline`, `url` and `omit`. `{other}` is the value given. See [`[[vcon.rule]]`](vcon.md#write-calls-by-rule).

**What to do:** Set `audio` to `inline`, `url` or `omit`.

**Exit code:** 1.

### `grouping = '{other}'; use 'leg' or 'call'`

The reason inside `[[vcon.rule]] '{name}' has {why}` for a `grouping` value other than `leg` and `call`. `{other}` is the value given. See [Calls through a PBX or a B2BUA](vcon.md#calls-through-a-pbx-or-a-b2bua).

**What to do:** Set `grouping` to `leg` (one container per dialog) or `call` (one per call).

**Exit code:** 1.

### `sealed_updates = '{other}'; use '{}', '{}' or '{}'`

The reason inside `[[vcon.rule]] '{name}' has {why}` for a `sealed_updates` value other than `new-uuid`, `same-uuid` and `final-only`, which fill the three `{}`. `{other}` is the value given. See [When an encrypted call changes](vcon.md#when-an-encrypted-call-changes).

**What to do:** Set `sealed_updates` to `new-uuid` (the default: each change is a new instance with a new uuid), `same-uuid` (rewrite the file under the same uuid) or `final-only` (write once, when the call ends), or remove the key.

**Exit code:** 1.

### `audio_format = '{other}'; use 'wav' or 'opus'`

The reason inside `[[vcon.rule]] '{name}' has {why}` for an `audio_format` value other than `wav` and `opus`. `{other}` is the value given. See [Audio as Ogg Opus](vcon.md#audio-as-ogg-opus).

**What to do:** Set `audio_format` to `wav` (the default) or `opus`, or remove the key.

**Exit code:** 1.

### `[[vcon.rule]] '{name}' has audio_format without audio = 'inline' or 'url': the rule carries no audio to format`

The [`[[vcon.rule]]`](vcon.md#write-calls-by-rule) named `{name}` sets `audio_format`, and its `audio` is `omit` or unset.

- An `omit` rule writes no audio, so `audio_format` would do nothing.

**What to do:** Remove `audio_format`, or set `audio = "inline"` or `"url"`.

**Exit code:** 1.

### `[[vcon.rule]] '{name}' has audio = 'url' and no audio_url_base: say where your storage serves the audio files sipnab writes beside the containers`

The [`[[vcon.rule]]`](vcon.md#write-calls-by-rule) named `{name}` has `audio = "url"` and no `audio_url_base`.

- A `url` rule writes each call's audio file beside its container, and names it by URL.
- That needs the base your storage serves the files from.

**What to do:** Add the HTTPS base your storage serves the files from, such as `audio_url_base = "https://media.example.com/vcon-audio"`, or use `audio = "inline"` or `"omit"`.

**Exit code:** 1.

### `[[vcon.rule]] '{name}' has audio_url_base '{base}': a vCon names external media over https (draft-ietf-vcon-vcon-core-04 section 2.4.1)`

The `audio_url_base` of the [`[[vcon.rule]]`](vcon.md#write-calls-by-rule) named `{name}` is not `https://`. `{base}` is the value. A vCon names external media over HTTPS.

**What to do:** Give an `https://` base URL.

**Exit code:** 1.

### `[[vcon.rule]] '{name}': 'when' is not a valid filter expression: {e}`

The `when` of the [`[[vcon.rule]]`](vcon.md#write-calls-by-rule) named `{name}` does not parse as a filter expression. `{e}` is the parser's reason. See [Filter DSL](filter-dsl.md).

**What to do:** Correct the expression. Test it first with `--filter`, giving the rule's `when` expression, such as `sipnab -N -I capture.pcap --filter "state == 'Failed'"`.

**Exit code:** 1.

### `[[vcon.rule]] '{name}': '@{reference}' is not a valid filter expression: {e}`

The `when` of the [`[[vcon.rule]]`](vcon.md#write-calls-by-rule) named `{name}` references the named filter `@{reference}`, and its expansion does not parse on its own. sipnab compiles each referenced name by itself to tag a container with the names the call matched. `{e}` is the parser's reason.

**What to do:** Correct that entry in `[filters]` so it is a complete expression by itself. Test it first with `sipnab -N -I capture.pcap --filter "@{reference}"`.

**Exit code:** 1.

### `[[vcon.rule]] '{name}' has {key} = '{header}', which is not a SIP header name: use letters, digits and '-', such as 'X-Queue'`

The `campaign_header`, `skill_header` or `interaction_id_header` of the [`[[vcon.rule]]`](vcon.md#write-calls-by-rule) named `{name}` is empty or holds a character a SIP header name cannot hold. `{key}` is the key and `{header}` the value. Such a name matches no header, and the Dialog parameter would stay empty on every call.

**What to do:** Write the header name alone, without a colon or a value, such as `skill_header = "X-Queue"`.

**Exit code:** 1.

### `[[vcon.rule]] '{name}': no filter`

The [`[[vcon.rule]]`](vcon.md#write-calls-by-rule) named `{name}` resolved to no filter at all. This is an internal check: a rule's `when` always gives one.

**What to do:** Report it, with the rule as written.

**Exit code:** 1.

### `[[vcon.rule]] '{name}': {}`

The `when` of the [`[[vcon.rule]]`](vcon.md#write-calls-by-rule) named `{name}` names a filter that does not resolve. `{}` is why: usually an `@name` that `[filters]` does not define, or a `[filters]` entry that does not resolve.

**What to do:** Define the name under `[filters]`, or correct the reference.

**Exit code:** 1.

### `[[vcon.rule]] with live_audio = true serves call audio on the REST API, and --api {addr} is not a loopback address. Off loopback, live audio needs TLS (--api-tls-cert and --api-tls-key) and a signing key (--api-signing-key or --api-signing-key-file) to mint tokens with the audio scope; or bind --api to 127.0.0.1`

A rule with `live_audio = true` serves call audio on the REST API. `--api` binds to an address other than loopback, without TLS and a signing key.

- `{addr}` is the address.
- See [Hear a call while it is in progress](vcon.md#hear-a-call-while-it-is-in-progress).

**What to do:** Bind `--api` to `127.0.0.1`, or give `--api-tls-cert`, `--api-tls-key` and `--api-signing-key-file`, and mint the transcriber a token with `--token-scope audio`.

**Exit code:** 1.

### `[[vcon.rule]] '{}' live_rtp = '{}' sends nothing in this run: only a headless run (-N) without --cores forks live audio`

A rule names a `live_rtp` target, and the run is a `--cores` run or the terminal UI. Neither sends live audio.

- The first `{}` is the rule's name, the second its target.
- See [Send a call's audio as RTP](vcon.md#send-a-calls-audio-as-rtp).

**What to do:** Run with `-N` and without `--cores` to send the audio.

**Exit code:** None. The run continues.

### `live_rtp: {} datagram(s) could not be sent to their target`

At the end of the run, the count of RTP packets and control messages a `live_rtp` rule could not send. A send fails when the target's port refuses it, or when the socket stays full for 20 ms.

- `{}` is the count.
- The receiver sees a gap in the sequence numbers of a leg that lost a packet.
- See [Send a call's audio as RTP](vcon.md#send-a-calls-audio-as-rtp).

**What to do:** Check that a program is reading the target's port, and that it keeps up with the audio.

**Exit code:** None. The run continues.

### `[[vcon.enrich]] name '{name}' is not usable: a name is 1 to {} ASCII letters, digits, '-' or '_', starting with a letter or digit`

An [`[[vcon.enrich]]`](vcon.md#enrich-a-call-before-it-is-written) has a `name` sipnab cannot use. `{name}` is the name, and `{}` is the longest a name may be.

**What to do:** Use 1 to 64 ASCII letters, digits, `-` or `_`, starting with a letter or digit.

**Exit code:** 1.

### `[[vcon.enrich]] name '{name}' is used by two enrichments; each needs its own`

Two [`[[vcon.enrich]]`](vcon.md#enrich-a-call-before-it-is-written) entries have the same `name`. The name is how a container records which service sipnab sent it to, so each must be unique.

**What to do:** Rename one of them.

**Exit code:** 1.

### `[[vcon.enrich]] cannot run with --redact: a service is sent the call as it was captured, and nothing it answers can be pseudonymized`

The run has `--redact` and an [`[[vcon.enrich]]`](vcon.md#enrich-a-call-before-it-is-written).

- sipnab sends a service the call as it captured it.
- It cannot replace what the service answers, such as a transcript, with pseudonyms.

**What to do:** Remove `--redact`, or remove the enrichment from this run.

**Exit code:** 2.

### `[limits] idle_compact_after_secs is {secs}, shorter than the {} s a live vCon export waits before it writes a call that has not ended, so idle compaction can drop that call's middle messages before its container is written. Set it to {} or more to keep them.`

A live capture exports vCons. `[limits] idle_compact_after_secs` is shorter than the time a live export waits before writing a call that has not ended.

- `{secs}` is the setting.
- The first `{}` is that wait in seconds. The second is the value to set.
- Idle compaction could drop the middle of such a call's messages before sipnab writes its container.

**What to do:** Set `[limits] idle_compact_after_secs` to the value named, or more.

**Exit code:** None. This is a warning, and the run continues.

## Capture and input files

### `Capture did not complete: {e:#}`

The capture thread stopped with an error before it read its whole input. So every report draws on only part of the input.

- `{e:#}` is the full error chain.
- The code names these causes:
  - sipnab could not open the capture;
  - libpcap rejected the BPF filter (the packet filter);
  - a read failed fatally;
  - a filter compiles for the first file of a set, but not for a later one.

**What to do:** Act on the error text: correct the filter or the file it names. The reports that sipnab printed before the exit are partial.

**Exit code:** 1.

### `Capture source failed to open: {e}`

The capture source (interface, file or socket) did not open. The text after the colon is the reason.

**What to do:** Check the device name, file path or address that you gave the run.

**Exit code:** 1.

### `Capture thread panicked; the input was not read to the end`

The capture thread crashed (a Rust panic) instead of returning.

- So sipnab did not read the input to the end.
- The reports draw on only part of it.

**What to do:** This is a crash inside sipnab, not a usage error. Run the command again to confirm it, and report it with the command line and, if possible, the input.

**Exit code:** 1.

### `--cores reads capture files in parallel and cannot read the stored vCon container '{}'. Drop --cores: a vCon is read on one core.`

`--cores` reads capture files on several cores, and its readers read packet captures. One of the `-I` inputs, named by `{}`, is a stored vCon container, which holds no packets. sipnab refuses the run before it reads anything.

**What to do:** Drop `--cores`, or read the vCon container in its own run.

**Exit code:** 2.

### `--cores: no capture files to read`

The multi-core reader (`--cores N` with `-I`) received an empty list of capture files.

- The code notes that the normal command line cannot reach this. Input resolution already fails the run when `-I` resolves to nothing.
- The check exists so the run cannot exit 0 with an empty report.

**What to do:** Pass `-I` with a capture file, directory or glob that contains at least one readable capture file.

**Exit code:** 1.

### `-I/--input: {e:#}`

sipnab could not turn the `-I`/`--input` values into a list of capture files to read.

`{e:#}` is the reason with its full chain of causes. For example:

- a path that does not exist;
- a glob pattern that matched no files;
- a directory with no capture files in it;
- a pattern that is not valid.

**What to do:** Correct the path, glob or directory given to `-I` so that it names at least one readable capture file. The reason after the colon names the value that failed.

**Exit code:** 1.

### `multi-core reconstruction failed: {e:#}`

The multi-core reader (`--cores N`) failed. `{e:#}` is the error chain.

- The code returns this error in these cases:
  - there are no files;
  - sipnab cannot open the first file of the `-I` set;
  - the BPF filter (the packet filter) does not compile against any file in the set.
- For a later file that sipnab cannot open, it logs the problem and skips the file instead.

**What to do:** Act on the error text: make the first file readable, or correct the BPF filter so it applies to every file in the set.

**Exit code:** 1.

### `{}\n  Available devices: {}\n  Try: sipnab -d {}`

The run names no capture source, and sipnab could not choose a default interface: there is no non-loopback interface to pick. The first placeholder is the detection error, then the interfaces found and the first of them. On Linux the default is always the `any` pseudo-device, so this message appears on other systems.

**What to do:** Name an interface with `-d`, for example the one the message suggests, or read a file with `-I <file>`.

**Exit code:** 1.

### `No capture device found. Use -d <device> or -I <file>\n  Try: sudo sipnab`

The run names no capture source (`-d`, `-I`, `-L`, a uprobe flag or `[capture] device`).

- sipnab tried to choose a default interface, and found none. The interface list is empty.
- On Linux the default is always the `any` pseudo-device. So this message appears on other systems.
- There, an empty list often means the user lacks capture permission.

**What to do:** Name a source with `-d <device>` or `-I <file>`, or run with sudo so that sipnab can read the interface list.

**Exit code:** 1.

### `not a frame pointer: {t}`

A shorter form of the malformed frame pointer refusal. `{t}` is the text.

- `--show-frame` reports a pointer it cannot parse with the longer message. That message starts "not a frame pointer" and continues "expected <source>#<ordinal>".
- The pointer lookup that follows parsing does not return this case.
- So the current `--show-frame` code does not reach this form.

**What to do:** Give a pointer of the form `<source>#<ordinal>` or `<source>#<ordinal>@<digest>`, copied from the `frame` field of sipnab's output.

**Exit code:** 2.

### `` not a frame pointer: {pointer}\nexpected <source>#<ordinal>, optionally #<ordinal>@<digest> — the form the `frame` field of --json-dialogs, --report, REST and MCP emits ``

The value given to `--show-frame` is not a frame pointer. `{pointer}` is the value. A frame pointer is `<source>#<ordinal>` (the capture and the zero-based frame number), optionally followed by `@<digest>`. It is the `frame` field that `--json-dialogs`, `--report`, the REST API and MCP print.

**What to do:** Copy the pointer exactly from the `frame` field of that output, for example `--show-frame capture.pcap#4212@<digest>`.

**Exit code:** 2.

### `--notes {}: {e}. sipnab will not start the TUI on it`

The notes file named by `--notes` exists, but sipnab cannot use it. So the terminal UI (TUI) does not start.

- `{}` is the path.
- `{e}` says why:
  - sipnab cannot read the file;
  - a line (by number) is not a note sipnab accepts;
  - the file holds more than 10000 notes.
- sipnab accepts a path that does not exist yet, and starts an empty notes session.

**What to do:** Do one of these:

- Fix the line the message names.
- Reduce the file to 10000 notes or fewer.
- Correct the file permissions.
- Name a new file with `--notes`.

**Exit code:** 2.

### `refusing: cannot read {source}: {cause}`

`--show-frame` could not open the capture the pointer names.

- `{source}` is the capture path from the pointer (or `<archive>/<member>` for a capture inside an archive).
- `{cause}` is the reason. For example, a missing file, a file that is not a capture, or an archive with no member of that name.

**What to do:** Run the command from the directory the pointer's path is relative to. Or make sure the capture still exists at that path and is readable.

**Exit code:** 1.

### `refusing: {source} frame {ordinal} is not the frame this pointer was made against. The capture was rotated, truncated or rewritten since then. Showing you what is there now would look like an answer and be the wrong one.`

The frame at position `{ordinal}` in `{source}` does not match the digest that sipnab recorded when it made the pointer. The digest is the checksum after `@` in the pointer.

- So someone or something has rotated, truncated or rewritten the capture since.
- sipnab refuses to show a different frame.

**What to do:** Find the original, unchanged capture that the pointer came from, or produce a new pointer from the current capture.

**Exit code:** 1.

### `refusing: {source} holds {frames_present} frame(s), so there is no frame {ordinal}`

The capture `{source}` holds `{frames_present}` frames, so the frame number `{ordinal}` in the pointer does not exist. Frame numbers start at 0. The capture may have lost frames to truncation since sipnab made the pointer.

**What to do:** Check that the pointer names the right capture. Check that the capture is the complete file that the pointer came from.

**Exit code:** 1.

### `refusing: read {ordinal} came from the TLS library inside {comm} (pid {pid}). sipnab read it out of the process, so it was never a frame on any wire — there is no capture to seek into and nothing to verify these bytes against.`

The pointer given to `--show-frame` names data that sipnab read through a uprobe. It is not a frame in a capture file. sipnab read the data from inside a running program's TLS library.

- `{ordinal}` is the read number.
- `{comm}` is the program's name and `{pid}` its process ID.
- There is no capture to read the bytes from.

**What to do:** None for this pointer. To see the bytes again, use the output of the run that captured them (for example its JSON output).

**Exit code:** 1.

### `unknown password encoding '{s}'; use utf-8, cp437, cp850 or cp1252`

`--archive-password-encoding` names the one text encoding that sipnab tries archive passwords in. `{s}` is the value you gave. sipnab accepts `utf-8` (or `utf8`), `cp437` (`ibm437`), `cp850` (`ibm850`) and `cp1252` (`windows-1252`), in any case, and reads `_` as `-`.

**What to do:** Give one of the accepted encodings, or leave the flag out to try the password in all of them.

**Exit code:** 2.

### `unknown severity {s:?}: expected info, notice, warning (or warn) or error`

`--lint-fail-on` names the lowest lint severity that fails the run with exit 3. `{s:?}` is the value you gave. sipnab accepts `info`, `notice`, `warning` (or `warn`) and `error`, in any case.

**What to do:** Give one of the four. `--lint-fail-on error` is the usual CI gate.

**Exit code:** 2.

## Output files and exports

### `{flag}: the answer did not serialize: {e}`

A query flag, named by `{flag}`, computed its answer, and sipnab could not write that answer as JSON or as a table. `{e}` is the serializer's reason. This indicates a fault in sipnab.

**What to do:** Report the message with the command line. Running without `--json` writes the answer as a table instead.

**Exit code:** 1.

### `analysis serialization failed: {e}`

`--json-analyze` prints the capture analysis as one JSON line, and converting the analysis to JSON failed. `{e}` is the serializer's error. The code comment calls this a bug in the analysis type. sipnab prints no `--json-analyze` line.

**What to do:** Use `--analyze` for the same analysis as a table.

**Exit code:** None. sipnab logs the error, and the exit status does not change.

### `Call-ID '{call_id}' not found in tracked dialogs`

`--call-report <CALL-ID>` asks for a detailed report of one call, `--call-tree <CALL-ID>` and `--correlate <CALL-ID>` for the legs of one call, and `--compare-dialogs <CALL-ID-A> <CALL-ID-B>` for two calls side by side. This run tracked no dialog with that exact Call-ID. The match is exact and case-sensitive. The run exits 1, and sipnab produces none of the later reports.

**What to do:** Run with `--report` (or `--json-dialogs`) to list the Call-IDs this run holds, then pass one of them exactly. The text `--report` table shortens Call-IDs to 30 characters, and `--markdown` shows them in full.

**Exit code:** 1.

### `Cannot emit --tshark-filter command: {e}`

`--tshark-filter <EXPR>` prints a ready-to-paste `tshark -r <file> -Y <EXPR>` command. sipnab could not name one file for `-r`.

- `{e}` is the reason. It is one of these:
  - there is no `-I` file and no `-O` file (a live capture that saved nothing);
  - the input is a member of an archive;
  - the input is several files.
- sipnab prints no command, and the run continues.

**What to do:** Use a single capture file with `-I`, or save a live capture with `-O <file>`. For an archive member, extract it first and run on the extracted file. For several files, run once per file.

**Exit code:** None. sipnab logs the error, and the run continues.

### `could not publish evidence`

`--evidence-out` writes one JSON line per security finding that names a source.

- `-` means standard output. Any other value names a file that sipnab opens for append.
- Writing one line failed.
- The log line carries `src_ip` (the source the finding is about) and `error` (the write or serialization error).
- The evidence output lacks that finding. Its alert still runs.

**What to do:** Check that the `--evidence-out` file accepts writes, and that its disk has space. Or check that the reader on the other end of standard output is still running.

**Exit code:** None. This is a warning, and the run continues.

### `--evidence-out {target}: {e}`

sipnab could not open the file named by `--evidence-out`, where it appends one line per security finding. `{target}` is the path as you gave it, and `{e}` is the operating system's reason. sipnab opens the file in create-and-append mode before it reads the first packet. The value `-` means standard output, and sipnab does not open it as a file.

**What to do:** Name a path whose directory exists, and that the user sipnab runs as can create or append to. Or pass `-` to write the findings to standard output.

**Exit code:** 2.

### `Failed to write DSB: {e:#}`

This applies with `--pcap-export-mode encrypted+dsb`, `--keylog <file>` and `--pcapng`.

- sipnab then embeds the TLS key log in the `-O` output as a Decryption Secrets Block (DSB). So Wireshark can decrypt the file.
- Writing that block to the output file failed.
- `{e:#}` is the writer's error.
- The capture continues, and the file has no embedded keys.

**What to do:** Check free space and write access for the `-O` location. To decrypt the file later without the block, open it in Wireshark together with the same key log file.

**Exit code:** None. This is a warning, and the run continues.

### `Failed to write name resolution block: {e:#}`

This applies with `--pcapng` and name resolution on (`--resolve`, `--reverse-dns`, or the `[names]` settings).

- sipnab then writes a Name Resolution Block at the start of the `-O` file. That block is a table of address-to-name entries.
- Writing that block failed.
- `{e:#}` is the writer's error.
- The capture continues without the block.

**What to do:** Check free space and write access for the `-O` location.

**Exit code:** None. This is a warning, and the run continues.

### `Failed to write output: {e}`

Writing the per-message output to standard output failed, for a reason other than a closed pipe. The per-message output is the printed messages, `--json` lines and similar.

- `{e}` is the error.
- The output is incomplete, so the run exits 1.
- sipnab does not count a closed pipe, such as `| head`, as an error.

**What to do:** Check that the destination of standard output has space and accepts writes. The destination is a file or disk you redirected it to.

**Exit code:** 1.

### `Failed to write packet: {}`

sipnab could not write a packet to the `-O` capture file. `{}` is the writer's error. When the cause is a permission refusal after sipnab dropped privileges, the message adds the user name and the remedies. In a headless run the capture loop stops, sipnab prints the reports, and the run exits 1. In the TUI the packet-processing thread stops.

**What to do:** Check free space and write access for the `-O` location.

If the message names a user that sipnab dropped privileges to, do one of these:

- give that user write access to the directory (for example `install -d -o <user> <dir>`);
- pass `--user <name>` for a user that can write there;
- pass `--no-priv-drop`.

**Exit code:** 1 in a headless run. In the TUI, this path sets no exit code.

### `Failed to write report: {e}`

sipnab could not write an end-of-run report to standard output.

- The reports are `--report`, `--json-dialogs`, `--stun`, `--json-stun`, `--analyze`, `--json-analyze`, `--yang-analyze`, `--hep-senders`, or `--export-vcon` to standard output.
- `{e}` is the error.
- sipnab does not count a closed pipe as an error.
- sipnab produces none of the reports after the failed one.

**What to do:** Check that the destination of standard output has space and accepts writes. The destination is a file or disk you redirected it to.

**Exit code:** 1.

### `--hep-senders: the roster did not serialize: {e}`

`--hep-senders` with `--json` prints the sender roster of the HEP listener as one JSON object. The roster says who sent HEP to this run, who went silent, and whom sipnab refused.

- Converting that roster to JSON failed.
- `{e}` is the JSON serializer's error.
- The run then exits.

**What to do:** Run without `--json` to get the same roster as a text table.

**Exit code:** 1.

### `No SIP dialogs to generate Wireshark filter for.`

`--wireshark` prints a Wireshark display filter that selects every tracked call by Call-ID. This run tracked no SIP dialogs, so there is no filter to print.

**What to do:** Check that the input or interface carries SIP. If the run summary shows a NOT ANALYZED line, apply the `--portrange` or `--ws-portrange` change it names.

**Exit code:** None. This is a warning, and the run continues.

### `--notes {notes_path}: {e}`

`--write-annotated` could not load the notes file named by `--notes` (`{notes_path}`). `{e}` says why:

- sipnab cannot read the file;
- a line is not a note sipnab accepts. The message gives its line number. One bad line refuses the whole file;
- the file holds more than 10,000 notes.

**What to do:** Correct the path or permissions, or fix the line the message names, then run the command again.

**Exit code:** 1.

### `--notes {notes_path} holds no notes, so there is nothing to annotate`

`--write-annotated` read the notes file named by `--notes` (`{notes_path}`) and found no notes in it (sipnab skips blank lines). A copy with no comments added would be identical to the input, so sipnab writes nothing.

**What to do:** Add notes to the file (for example from the TUI), or name a notes file that contains them. Then run the command again.

**Exit code:** 1.

### `-O/--output cannot write a run that captures from two sources. '{out}' would be initialized from whichever member's first packet arrived first, and the two disagree about the link layer: the interface yields Ethernet frames, while HEP delivers a bare SIP payload with no link, IP or transport header to write. Capture the interface alone to write a pcap, or use --hep-send <ADDR> to forward the signaling to a collector instead of writing it.`

`-O/--output` writes a capture file. This run captures from two sources at once:

- a live interface (`-d` or the config file's device);
- a HEP listener (`-L`).

The interface delivers Ethernet frames. HEP delivers bare SIP text with no link, IP or transport header. So one file cannot hold both. `{out}` is the `-O` path.

**What to do:** Do one of these:

- Capture the interface alone (without `-L`) to write a pcap.
- Keep both sources, and use `--hep-send <ADDR>` to forward the signaling to a collector instead of `-O`.

**Exit code:** 2.

### `Output file may be incomplete: {e:#}`

At the end of the run, the final flush of the `-O` capture file failed. So the end of the file may be missing.

- `{e:#}` is the error chain.
- In a headless run the exit code is 1.

**What to do:** Check free space and write access for the `-O` location, and treat the file as truncated.

**Exit code:** 1 in a headless run. In the TUI, this path sets no exit code.

### `plugin {}: {e}`

sipnab could not load a `--plugin` file.

- `{}` is the path.
- `{e}` is the reason:
  - sipnab could not read the file;
  - the file is not valid WebAssembly;
  - it lacks a required export;
  - it reports an ABI version this build does not support.
- The run still produces its reports. They carry a marker naming the failure. The run exits 1.

**What to do:** Correct the path, or rebuild the plugin against the plugin ABI version this sipnab build reports.

**Exit code:** 1.

### `plugin {} on {}: {e}`

A `--plugin` (a WebAssembly analysis module) failed while it analyzed one dialog for `--json-dialogs`.

- The first `{}` is the plugin name. The second is the Call-ID.
- `{e}` is the reason. For example, the plugin trapped, ran out of its limits, or returned output in the wrong shape.
- sipnab prints that dialog's line without this plugin's findings.

**What to do:** Check the plugin that the message names against the dialog it names. The error text says which kind of failure occurred.

**Exit code:** None. sipnab logs the error, and the run continues.

### `--print-yang-module: {e}`

`--print-yang-module` writes the YANG module text (the data model sipnab's [RFC 7951](https://www.rfc-editor.org/rfc/rfc7951.html) JSON export follows) to standard output, and the write failed. `{e}` is the error, for example a pipe whose reader has already closed.

**What to do:** Make sure standard output is writable, for example redirect it to a file: `sipnab --print-yang-module > sipnab.yang`.

**Exit code:** 1.

### `RFC 7951 encoding failed: {e}`

`--yang-analyze` prints the capture analysis encoded as RFC 7951 JSON (the JSON encoding of YANG-modeled data) against the `sipnab-diagnosis` model. Encoding failed. `{e}` is the reason. The code describes this as a mismatch inside sipnab between the analysis and its YANG table. sipnab prints no `--yang-analyze` line.

**What to do:** Use `--json-analyze` for the same analysis as plain JSON, or `--analyze` for the table.

**Exit code:** None. sipnab logs the error, and the exit status does not change.

### `--strip-secrets failed: {e}`

`--strip-secrets` writes a copy of a `pcapng` capture with every Decryption Secrets Block removed. That block stores TLS keys inside a `pcapng` file. The copy failed.

- `{e}` is the reason:
  - sipnab cannot read the input;
  - the input is larger than the in-memory size limit;
  - it is not `pcapng`;
  - a block has a truncated or invalid length;
  - sipnab cannot write the output.
- sipnab never modifies the input file.

**What to do:** Act on the reason given. For a file over the size limit, raise `--max-metadata-file-bytes` or `[limits] max_metadata_file_bytes`. A classic pcap has no secrets blocks to strip.

**Exit code:** 1.

### `--strip-secrets requires an input file (-I <file>)`

`--strip-secrets <OUT>` copies one input capture, and the command line names no input.

**What to do:** Name the capture to copy with `-I`, for example `sipnab --strip-secrets clean.pcapng -I capture.pcapng`.

**Exit code:** 1.

### `` the input '{}' is a member of an archive, and `tshark -r` reads one capture file; extract that member and point tshark at it ``

Part of the `Cannot emit --tshark-filter command:` message. The single input is a file that sipnab extracted from an archive and deletes after the run. `tshark -r` cannot read inside an archive, so sipnab prints no command. `'{}'` names the member.

**What to do:** Extract that member from the archive. Then point `tshark` at the extracted file, or run sipnab with `-I` on the extracted file.

**Exit code:** None. sipnab logs the error, and the run continues.

### `` the input is {} files and `tshark -r` reads one, so no single command covers this run. The display filter below names Call-IDs from all of them; a command reading only one would silently return a subset. Files: {} ``

Part of the `Cannot emit --tshark-filter command:` message. The input is several files, and `tshark -r` reads one, so no single command covers the run, and sipnab prints none. The first `{}` is the number of files, and the second lists them.

**What to do:** Run sipnab once per file to get one command per file, or merge the files into one capture first.

**Exit code:** None. sipnab logs the error, and the run continues.

### `--tui-audit-file {path}: {e}. sipnab refuses to run the TUI without the action trail it was asked for`

sipnab could not open the file named by `--tui-audit-file` for appending. sipnab does not run the TUI without the record of operator actions you asked for. `{path}` is the path given, and `{e}` is the operating system error. sipnab opens the file in append mode and creates it with mode 0600 if it does not exist.

**What to do:** Name a path in a directory that exists and that the sipnab user can write. Or fix the permissions of the existing file.

**Exit code:** 2.

### `--write-annotated needs --notes <FILE>`

`--write-annotated` writes a copy of a capture with notes added as packet comments. The notes come from the file named by `--notes`.

- The command line has no `--notes`.
- The command-line parser normally refuses this combination first. This check is a second guard.

**What to do:** Add `--notes <FILE>` naming the notes file.

**Exit code:** 2.

### `--write-annotated refused: {e}. Nothing was written to {out}.`

sipnab did not write the annotated copy.

- `{e}` is the reason.
- `{out}` is the output path. sipnab left no file there.
- The reasons include the following:
  - The output name ends in a classic pcap extension. Classic pcap has no comment field.
  - A note's frame pointer has no `@<digest>`, names another capture, or names text that sipnab read through a uprobe.
  - The capture holds fewer frames than a note names.
  - A frame no longer matches its digest.
  - sipnab cannot represent a frame timestamp.
  - sipnab cannot read the capture, or cannot write the copy.

**What to do:** Act on the reason given.

- Name the output `.pcapng`.
- Take frame pointers from `--json` output over the same capture. They end in `@<digest>`.
- Annotate one capture per run, against the unchanged capture that you wrote the notes for.

**Exit code:** 1.

### `--write-annotated requires an input capture (-I <file>)`

`--write-annotated` copies one input capture, and the command line has no `-I`.

**What to do:** Name the capture with `-I`, for example `sipnab --notes notes.jsonl --write-annotated out.pcapng -I capture.pcapng`.

**Exit code:** 1.

### `--write-annotated {out} would overwrite the notes file it reads; name another output`

The output path given to `--write-annotated` (`{out}`) is the same file as the notes file it reads. It has the same spelling, or is the same file after resolving links. Writing it would destroy the notes.

**What to do:** Give `--write-annotated` a different output path.

**Exit code:** 2.

### `{flag} writes {}, but -I resolved to {} files: {names}. {}`

`--strip-secrets` and `--write-annotated` each write one output file from one input capture. Here `-I` resolved to several files. That flag accepts directories, globs and repeated paths.

- `{flag}` is the command.
- The next placeholder is what it writes. Then comes the file count.
- `{names}` is the resolved files.
- The last placeholder is the advice.
- sipnab refuses rather than handle only the first file.

**What to do:** Run the command once per capture, giving `-I` a single file each time.

**Exit code:** 1.

## Servers: REST API, metrics and MCP

### `actions are off for this run: {why}`

sipnab switched actions off for this run because it found damage in the actions journal. Actions are bans and unbans that sipnab asks TFPS, a firewall service, to apply. `--allow-action` enables them. `{why}` names the journal file, the record number and what does not match. Everything that only reads keeps working.

**What to do:** Inspect the journal file the message names, in the directory given by `--journal-dir` or `[journal] dir` (default `/var/lib/sipnab/journal`). Actions stay off until an operator has looked at it.

**Exit code:** None. sipnab logs the error, and the run continues with actions off.

### `actions journal: {} action(s) from the last run are still in doubt because TFPS could not be asked; new actions are refused until they are resolved`

The actions journal records actions from the previous run whose result is unknown. For example, sipnab stopped while it was sending a ban.

- sipnab could not ask TFPS about them at startup.
- `{}` is how many.
- sipnab refuses new bans and unbans until TFPS answers.

**What to do:** Make TFPS reachable at the address in the sipnab configuration. sipnab asks TFPS again once a minute and resolves the actions when it answers.

**Exit code:** None. This is a warning, and the run continues.

### `actions: the check against TFPS could not start: {e}`

sipnab could not create the thread that checks the actions journal against TFPS once a minute, so sipnab refuses the run. `{e}` is the operating system error.

**What to do:** Act on the operating system reason in `{e}` and run again. Or run without `--allow-action`, so that sipnab starts no check thread.

**Exit code:** 2.

### `Failed to build the shared server runtime: {e}`

The thread that runs the REST API and MCP servers could not create its async runtime, so none of those servers run. `{e}` is the error from the runtime builder. sipnab bound the listeners before this point, and the rest of the run continues.

**What to do:** The message carries the operating system's reason in `{e}`. The code offers no setting that changes this step. Address that reason, then restart the run.

**Exit code:** None. sipnab logs the error, and the run continues without the REST API and MCP servers.

### `Failed to create HEP sender: {e:#}`

sipnab could not set up the connection that `--hep-send` uses. That connection forwards captured packets in HEP (Homer Encapsulation Protocol) format.

- `{e:#}` is the reason with its full chain of causes:
  - the destination address did not resolve;
  - sipnab could not bind a local UDP socket;
  - there is no route to the destination;
  - the TCP or TLS connection failed;
  - for `--hep-send-transport tls`, the destination has no host name to check the certificate against.
- The run stops instead of running without forwarding.

**What to do:** Correct the `--hep-send` address (`HOST:PORT`), or the transport flags named in the reason. Make sure the collector is reachable from this host.

**Exit code:** 2.

### `Failed to spawn the servers thread: {e}`

The operating system refused to create the thread that runs the REST API and MCP servers. `{e}` is the operating system error.

**What to do:** Act on the operating system reason in `{e}` and run again. Or run without `--api` and `--mcp`, so that sipnab starts no servers thread.

**Exit code:** 2.

### `Failed to start metrics server: {e}`

The Prometheus metrics endpoint that you asked for with `--metrics` could not start. `{e}` gives the reason:

- the address is not a loopback address, and you gave no `--metrics-auth` or `--metrics-auth-file`;
- or sipnab could not bind the port, for example because another program uses it;
- or sipnab could not create the server thread.

**What to do:** Bind to `127.0.0.1`, or supply `--metrics-auth` or `--metrics-auth-file` for a routable address. Choose a free port, or remove `--metrics`.

**Exit code:** 2.

### `Invalid --api address: {e}`

The value of `--api` is not an address sipnab can listen on. `{e}` repeats the value and the parse error. sipnab accepts a port (`8080`), `:port`, or `address:port` (`127.0.0.1:8080`, `[::1]:8080`).

**What to do:** Give `--api` a port or an `address:port` value, for example `--api 127.0.0.1:8080`.

**Exit code:** 2.

### `invalid bind address '{input}': {reason}`

sipnab could not parse a listener address for `--api`, `--metrics` or `--mcp-bind`.

- `{input}` is the value.
- `{reason}` repeats it with the parser's error.
- sipnab accepts:
  - a port (`8080`);
  - `:port` (both bind 127.0.0.1);
  - `address:port`, such as `0.0.0.0:8080` or `[::1]:8080`.
- The line starts with `Invalid --api address:`, `Invalid --metrics address:` or `Invalid --mcp-bind address:`.

**What to do:** Give the address in one of the accepted forms, with a port from 0 to 65535.

**Exit code:** 2.

### `Invalid --mcp-bind address: {e}`

The value of `--mcp-bind` (the listening address for MCP over HTTP) is not an address sipnab can listen on. `{e}` repeats the value and the parse error. sipnab accepts a port, `:port`, or `address:port`. The default is `127.0.0.1:8731`.

**What to do:** Give `--mcp-bind` a port or an `address:port` value, for example `--mcp-bind 127.0.0.1:8731`.

**Exit code:** 2.

### `Invalid --metrics address: {e}`

sipnab could not parse the `--metrics` address (where the Prometheus metrics server listens). `{e}` repeats the value and the reason. The accepted forms are a port number (`9090`), `:port` (both bind 127.0.0.1), or a numeric `IP:port`. sipnab does not accept host names.

**What to do:** Use a form such as `--metrics 9090`, `--metrics :9090` or `--metrics 0.0.0.0:9090`.

**Exit code:** 2.

### `--journal-show and --revert-actions need the 'api' or 'mcp' feature (not compiled in): no action can have been taken`

`--journal-show` and `--revert-actions` read the journal of actions that the REST API or MCP server took.

- This sipnab build does not include the code for them.
- So there is no journal, and this build cannot have taken any action.

**What to do:** Use a sipnab build compiled with the `api` or `mcp` feature on a Unix system, or remove the flags.

**Exit code:** 2.

### `--mcp-audit-file {path}: {e}. sipnab refuses to serve MCP without the audit trail it was asked for`

sipnab could not open the file named by `--mcp-audit-file` for appending.

- sipnab does not start MCP without the record of tool calls you asked for. MCP (Model Context Protocol) is the interface AI assistants use to query sipnab.
- `{path}` is the path given.
- `{e}` is the operating system error.
- sipnab opens the file in append mode. It creates it with mode 0600 if it does not exist.

**What to do:** Name a path in a directory that exists and that the sipnab user can write. Or fix the permissions of the existing file.

**Exit code:** 2.

### `--mcp-tls-cert/--mcp-tls-key serve MCP over HTTPS and do nothing without --mcp --mcp-transport http`

`--mcp-tls-cert` and `--mcp-tls-key` are the certificate and private key that the MCP (Model Context Protocol) server presents when it serves over HTTP. They make it HTTPS.

- You gave at least one of them.
- But the run does not serve MCP over HTTP. Either `--mcp` is absent, or `--mcp-transport` is not `http` (the default is `stdio`).

**What to do:** Add `--mcp --mcp-transport http`, or remove `--mcp-tls-cert` and `--mcp-tls-key`.

**Exit code:** 2.

### `--mcp-token-file '{path}': {e}`

sipnab could not read the file named by `--mcp-token-file`. The file holds the static token that MCP over HTTP accepts. `{path}` is the path given, and `{e}` is the operating system error. sipnab reads the file only when you do not give `--mcp-token`.

**What to do:** Correct the path or the file permissions, or pass the token with `--mcp-token` or the `SIPNAB_MCP_TOKEN` environment variable instead.

**Exit code:** 2.

### `--mcp-transport http requires the mcp-http feature; rebuild with --features mcp-http (or full).`

You gave `--mcp-transport http`, but this sipnab binary does not include the `mcp-http` build feature, so it cannot serve MCP over HTTP.

**What to do:** Use `--mcp-transport stdio`, or use a build that includes the `mcp-http` feature (for example one built with `--features mcp-http` or `--features full`).

**Exit code:** 2.

### `--mcp requires the 'mcp' feature (not compiled in)`

`--mcp` runs sipnab as an MCP (Model Context Protocol) server. This sipnab build does not include the `mcp` feature, so it has no MCP server. sipnab refuses the run before it opens the capture.

**What to do:** Use a sipnab build that includes the `mcp` feature, or remove `--mcp`.

**Exit code:** 2.

### `--api requires the 'api' feature (not compiled in)`

`--api` starts the REST API server. This sipnab build does not include the `api` feature, so it has no REST API server. sipnab refuses the run before it opens the capture.

**What to do:** Use a sipnab build that includes the `api` feature, or remove `--api`.

**Exit code:** 2.

### `--api-key requires the 'api' feature (not compiled in)`

`--api-key` sets the key that the REST API server accepts. This sipnab build does not include the `api` feature, so it has no REST API server. sipnab refuses the run before it opens the capture.

**What to do:** Use a sipnab build that includes the `api` feature, or remove `--api-key`.

**Exit code:** 2.

### `--api-tls-cert requires the 'api' feature (not compiled in)`

`--api-tls-cert` names the certificate chain that the REST API server presents over HTTPS. This sipnab build does not include the `api` feature, so it has no REST API server. sipnab refuses the run before it opens the capture.

**What to do:** Use a sipnab build that includes the `api` feature, or remove `--api-tls-cert`.

**Exit code:** 2.

### `--api-tls-key requires the 'api' feature (not compiled in)`

`--api-tls-key` names the private key for `--api-tls-cert`. This sipnab build does not include the `api` feature, so it has no REST API server. sipnab refuses the run before it opens the capture.

**What to do:** Use a sipnab build that includes the `api` feature, or remove `--api-tls-key`.

**Exit code:** 2.

### `--mcp uses stdout for the JSON-RPC wire and cannot be combined with stdout-writing flags ({})`

`--mcp` starts the MCP (Model Context Protocol) server, and with the default stdio transport its JSON-RPC messages travel on standard output. The flags listed in parentheses also write to standard output, and sipnab refuses them alongside `--mcp`. The list includes `--export-vcon` only when you did not give `--vcon-out`.

**What to do:** Remove the listed flags from the `--mcp` run. For `--export-vcon`, add `--vcon-out FILE` so that sipnab writes the container to a file instead of standard output.

**Exit code:** 2.

### `metrics auth: {e}`

sipnab could not resolve the metrics endpoint credential. `{e}` says why: sipnab cannot read the file named by `--metrics-auth-file`, the file is empty, or `--metrics-auth` has an empty value. sipnab refuses to start the endpoint rather than run it without the authentication you asked for.

**What to do:** Correct the path or permissions of `--metrics-auth-file`, put the credential in it, or give `--metrics-auth` a non-empty value. To run without authentication, remove both flags and bind `--metrics` to a loopback address.

**Exit code:** 2.

### `metrics TLS: {e:#}`

sipnab could not set up HTTPS for the metrics endpoint. `{e:#}` gives the reason:

- you gave only one of `--metrics-tls-cert` and `--metrics-tls-key`;
- sipnab cannot read a file;
- the certificate file holds no certificate;
- the key file holds no private key;
- other users can read the key;
- the key does not belong to the certificate.

**What to do:**

- Give both `--metrics-tls-cert` and `--metrics-tls-key`.
- Point them at a matching PEM certificate chain and private key.
- Make the key file unreadable by other users (for example `chmod 600` or `chmod 640`).

**Exit code:** 2.

### `--mint-token requires the 'api' or 'mcp' feature (not compiled in)`

`--mint-token` creates a signed bearer token for the REST API or the HTTP MCP server. This sipnab build has neither the `api` nor the `mcp` feature, so it has no token signer.

**What to do:** Use a sipnab build compiled with the `api` or `mcp` feature.

**Exit code:** 2.

### `server error: {0}`

The REST API server (`--api`) could not start, or stopped with an error.

- `{0}` says why:
  - sipnab could not bind the address;
  - the command gave only one of `--api-tls-cert` and `--api-tls-key`;
  - a TLS file is unusable;
  - the bind is not loopback, and no `--api-key` or `--api-signing-key` exists;
  - sipnab could not set up the listener.
- At startup this stops the run before the TUI or capture begins.
- After startup, sipnab logs the error as `API server error:` followed by the reason. The API stops serving.

**What to do:** Act on the reason in `{0}`:

- free or change the `--api` port;
- give both TLS files;
- bind `127.0.0.1`;
- or, for a bind that is not loopback, configure `--api-key` (`SIPNAB_API_KEY`) or `--api-signing-key` (`SIPNAB_API_SIGNING_KEY`).

**Exit code:** 2 at startup. None for an error after startup: sipnab logs it, and the run continues.

### `{name} server error: {e}`

A server running beside the capture stopped with an error. `{name}` is `API`, `MCP stdio` or `MCP HTTP`, and `{e}` is the error. The other servers and the capture keep running.

**What to do:** Read `{e}` for the cause. sipnab does not restart the server during the run, so restart sipnab after you correct the cause.

**Exit code:** None. sipnab logs the error, and the run continues.

### `{}: these opt-ins act on the sipnab process or the relay, and with the TUI up the operator at the terminal owns both. Add -N to serve MCP headless with them, or remove them to query this capture beside the TUI`

The listed options let an MCP (Model Context Protocol) client act on the sipnab process or on the media relay. They come from `--mcp-allow-shutdown`, `--mcp-allow-open-capture`, `--mcp-allow-tls-capture`, `--mcp-allow-save-findings` and `--mcp-allow-relay-query`.

- You gave them on a run that serves MCP over HTTP while the interactive terminal interface (TUI) is running.
- sipnab refuses them there.

**What to do:** Do one of these:

- Add `-N` to serve MCP without the TUI, and keep the options.
- Remove the listed options to query the capture while the TUI runs.

**Exit code:** 2.

### `token TTL must be positive, got {ttl}`

`--mint-token` takes the token lifetime from one of two flags:

- from `--api-token-ttl` when the configuration has a REST API signing key;
- otherwise from `--mcp-token-ttl`.

That value is 0 or negative. `{ttl}` is the value in seconds. Both flags default to 3600.

**What to do:** Give a positive number of seconds to the flag that applies, for example `--api-token-ttl 3600`.

**Exit code:** 2.

### `{flag} '{path}': {e}`

sipnab could not read the signing-key file. `{flag}` is `--api-signing-key-file` or `--mcp-signing-key-file`, `{path}` is the file, and `{e}` is the operating system's reason.

**What to do:** Check the path, and check that the user sipnab runs as can read the file.

**Exit code:** 2.

## Media relays (rtpengine and rtpproxy)

### `{} answered {other:?}, not statistics`

A `--relay-stats-interval` poll got a reply that was not a statistics answer. The first `{}` is `rtpengine at <addr>`, and `{other:?}` is the decoded reply. The poll keeps running on its interval.

**What to do:** Check that `--rtpengine-control` points at the relay's control port.

**Exit code:** None. sipnab logs the error, and the run continues.

### `could not start the relay statistics poller ({e}); nothing polled`

sipnab could not create the thread that polls relay statistics for `--relay-stats-interval`. `{e}` is the operating system's error from thread creation. No polling happens, and the rest of the run continues.

**What to do:** Act on the error text, then run again.

**Exit code:** None. This is a warning, and the run continues.

### `could not start the rtpengine reconciler ({e}); streams the signaling does not explain will stay unattributed`

With `--rtpengine-control` on a live source, sipnab starts a background thread. The thread asks the relay about RTP streams the SIP signaling does not explain.

- sipnab could not create that thread.
- `{e}` is the error.
- The capture continues. Such streams stay without a call attribution.

**What to do:** Act on the error text, then run again.

**Exit code:** None. This is a warning, and the run continues.

### `{} did not answer the polled statistics request ({e})`

A `--relay-stats-interval` poll failed. The first `{}` is `rtpengine at <addr>`, and `{e}` is the error. The request times out after 2 seconds. The poll keeps running on its interval.

**What to do:** Check that the relay is running. Check that `--rtpengine-control` names its control port, and that this host can reach that port.

**Exit code:** None. sipnab logs the error, and the run continues.

### `relay at {addr} answered {other:?}, not per-call statistics`

For `--relay-compare`, sipnab asked the relay at `{addr}` for the statistics of one call and received a reply of another kind. `{other:?}` is that reply in sipnab's internal debug form. sipnab compared nothing.

**What to do:** Check that `--rtpengine-control` points at the relay's ng control port and that the relay is rtpengine.

**Exit code:** None. sipnab logs the error, and the run continues.

### `relay at {addr} answered {other:?}, not statistics`

For `--relay-stats`, `--relay-stats-call` or `--relay-stats-list`, sipnab asked the relay at `{addr}` for statistics and received a reply of another kind. `{other:?}` is that reply in sipnab's internal debug form. sipnab printed nothing.

**What to do:** Check that `--rtpengine-control` points at the relay's ng control port and that the relay is rtpengine.

**Exit code:** None. sipnab logs the error, and the run continues.

### `relay at {addr} did not answer the per-call statistics request for call {call_id} ({e}); sipnab measured {measured} RTP packet(s), but the relay's side did not arrive.`

The relay at `{addr}` did not answer the per-call statistics request for call `{call_id}`. `{e}` is the error, and `{measured}` is sipnab's own RTP packet count. The run continues.

**What to do:** Check the `--rtpengine-control` address, and check that the relay is reachable.

**Exit code:** None. sipnab logs the error, and the run continues.

### `relay at {addr} did not answer the statistics request ({e}); asked, nothing came back.`

The relay at `{addr}` did not answer the `--relay-stats` request. `{e}` is the error. Over UDP, a timeout cannot tell a stopped relay from a filtered port or a lost reply. The run continues.

**What to do:** Check the `--rtpengine-control` address and port, and check that the relay is running and reachable.

**Exit code:** None. sipnab logs the error, and the run continues.

### `relay at {addr} refused the per-call statistics request for call {call_id}: {reason}; nothing to compare.`

For `--relay-compare`, the relay at `{addr}` answered the per-call statistics request for `{call_id}` with an error. `{reason}` is the relay's own reason, for example an unknown Call-ID. sipnab compared nothing.

**What to do:** Check the Call-ID given to `--relay-compare` and that the call is still active on that relay.

**Exit code:** None. sipnab logs the error, and the run continues.

### `relay at {} refused the statistics request for call {call_id}: {reason}`

For `--relay-stats-call <CALL-ID>`, the relay (`{}` is its address) answered the statistics request for `{call_id}` with an error. `{reason}` is the relay's own reason, for example an unknown Call-ID.

**What to do:** Check the Call-ID and that the call is active on that relay. `--relay-stats` without a Call-ID asks for the relay-wide statistics.

**Exit code:** None. sipnab logs the error, and the run continues.

### `relay at {addr} reported {digits} RTP packet(s) for call {call_id}, a value too large to compare; the answer is suspect, carried as received and not truncated.`

For `--relay-compare`, the relay at `{addr}` reported an RTP packet count for call `{call_id}` that does not fit in a 64-bit number. `{digits}` is the value as received. sipnab treats the answer as suspect and does not compare it or shorten it.

**What to do:** No sipnab setting changes this, because the value comes from the relay. Check the relay's own statistics for that call.

**Exit code:** None. sipnab logs the error, and the run continues.

### `relay at {addr}: {e}; the reply for call {call_id} was discarded and not read (suspect). sipnab measured {measured} RTP packet(s).`

The relay at `{addr}` answered the `--relay-compare` request for call `{call_id}` with a reply sipnab could not trust, so sipnab discarded it. `{measured}` is sipnab's own RTP packet count for the call. The run continues.

**What to do:** Retry, and check that nothing else uses the same control channel.

**Exit code:** None. sipnab logs the error, and the run continues.

### `relay at {addr}: {e}; the reply was discarded and not read (suspect).`

The relay at `{addr}` answered `--relay-stats` with a reply sipnab could not trust: one whose cookie answers a different request, or one sipnab cannot decode. So sipnab discarded the reply. The run continues.

**What to do:** Check that `--rtpengine-control` names the relay's ng control port and that only one client talks to it with this address, then retry.

**Exit code:** None. sipnab logs the error, and the run continues.

### `--relay-compare needs a relay to ask. Name one with --rtpengine-control <addr>.`

`--relay-compare <CALL-ID>` asks the media relay (rtpengine) for its RTP packet count for one call. But the command line has no relay address in `--rtpengine-control`. So sipnab asked nothing.

**What to do:** Add `--rtpengine-control <ip:port>` with the relay's ng control port, for example `--rtpengine-control 127.0.0.1:22222`.

**Exit code:** None. sipnab logs the error, and the run continues.

### `--relay-compare will not ask a relay on a run that reads a file: asking transmits. Compare from a live capture (-d <device>).`

Asking the relay sends a packet. sipnab does not transmit during a run without a live network source. So `--relay-compare` asked nothing.

**What to do:** Run the comparison during a live capture, for example with `-d <device>`.

**Exit code:** None. sipnab logs the error, and the run continues.

### `--relay-holdings needs a relay to ask. Name one with --rtpengine-control <addr>, for example --rtpengine-control 127.0.0.1:22222.`

`--relay-holdings` asks a media relay which calls it holds, but the run has no relay address to ask. The command line refuses `--relay-holdings` without `--rtpengine-control` before this point, so this message is a fallback. sipnab asked nothing.

**What to do:** Add `--rtpengine-control <ip:port>`, for example `--rtpengine-control 127.0.0.1:22222`.

**Exit code:** 2.

### `--relay-holdings will not ask a relay on a run that reads a file: asking transmits. Ask from a live source (-d <device> or -L <addr>).`

Asking the relay sends a packet. sipnab transmits only on a run that watches a live source: a network interface or a HEP listener. This run reads a capture file, so `--relay-holdings` asked nothing and printed no answer.

**What to do:** Ask from a live source, for example `-d <device>` or `-L <addr>`.

**Exit code:** 2.

### `--relay-holdings: {}`

`--relay-holdings` asked the relay which calls it holds, and no call list came back. `{}` names the classification and what happened:

- `unreachable`: no reply arrived within the timeout. Over UDP, a relay that is down, a filtered port and a lost reply look the same.
- `refused`: the relay answered and declined, in its own words.
- `suspect`: a reply arrived that sipnab cannot trust: one for another request, one sipnab cannot decode, or one that is not a call list.

This is not a relay that holds no calls. That answer prints `The relay holds no calls.` and exits 0.

**What to do:** For `unreachable`, check that `--rtpengine-control` names the relay's ng control port and that the relay is running. For `refused`, read the relay's reason. For `suspect`, ask again. If it repeats, look at the relay, or at something else answering on its port.

**Exit code:** 1.

### `--relay-stats-interval needs a relay to poll. Name one with --rtpengine-control <addr>.`

`--relay-stats-interval` asks sipnab to poll a media relay's statistics every N seconds, but the command names no relay, so sipnab polls nothing. The rest of the run continues.

**What to do:** Add `--rtpengine-control <addr:port>` with the relay's control port (for example `127.0.0.1:22222`), or remove `--relay-stats-interval`.

**Exit code:** None. sipnab logs the error, and the run continues.

### `--relay-stats-interval will not poll a relay on a run that reads a file: polling transmits. Poll from a live capture (-d <device>).`

Polling a relay sends packets, and sipnab transmits only on a run that watches a live source. This run's source does not permit transmitting, so sipnab polls nothing, and the rest of the run continues. A live interface and a HEP listener permit transmitting. Capture files and uprobe reads do not.

**What to do:** Do one of these:

- Run the poll from a live capture (`-d <device>`) or a HEP listener (`--hep-listen`).
- Remove `--relay-stats-interval` from runs that read files.

**Exit code:** None. sipnab logs the error, and the run continues.

### `--relay-stats needs a relay to ask. Name one with --rtpengine-control <addr>, for example --rtpengine-control 127.0.0.1:22222.`

`--relay-stats`, `--relay-stats-call` or `--relay-stats-list` asks the media relay (rtpengine) for its own statistics. But the command line has no relay address in `--rtpengine-control`. So sipnab asked nothing.

**What to do:** Add `--rtpengine-control <ip:port>`, for example `--rtpengine-control 127.0.0.1:22222`.

**Exit code:** None. sipnab logs the error, and the run continues.

### `--relay-stats will not ask a relay on a run that reads a file: asking transmits, and a file's addresses are historical and belong to third parties. Ask from a live capture (-d <device>).`

Asking the relay sends a packet. sipnab does not transmit during a run without a live network source.

- So the relay statistics request (`--relay-stats`, `--relay-stats-call` or `--relay-stats-list`) asked nothing.
- The addresses in a capture file are historical, and belong to other parties.

**What to do:** Ask from a live capture, for example `-d <device>`.

**Exit code:** None. sipnab logs the error, and the run continues.

### `--rtpengine-control {addr} asks a live relay which calls are up right now, but this run is reading a capture FILE — offline analysis never transmits. The calls in a file ended in the past; the relay's answer would describe whatever is up TODAY, which is other people's traffic. Passive decoding of any relay control plane already in the capture still runs; capture live with -d <device> to ask.`

A warning: `--rtpengine-control {addr}` asks a live relay which calls are active now. This run has no live network source, so sipnab does not ask.

- The calls in a capture file ended in the past.
- The relay's answer would describe current calls.
- sipnab still decodes any relay control traffic present in the capture.

**What to do:** Capture live with `-d <device>` to have sipnab ask the relay, or remove `--rtpengine-control` from file runs.

**Exit code:** None. This is a warning, and the run continues.

### `--rtpengine-control {addr} is not an address and port ({e}).`

The `--rtpengine-control` value `{addr}` is not an IP address and port, so `--relay-compare` asked nothing. `{e}` is the parse error. sipnab accepts only a numeric `IP:port` form and does not resolve host names.

**What to do:** Give the relay's ng control address as `IP:port`, for example `--rtpengine-control 127.0.0.1:22222`.

**Exit code:** None. sipnab logs the error, and the run continues.

### `--rtpengine-control {addr} is not an address and port ({e}). It names the relay's ng control port, for example 127.0.0.1:22222. Nothing was asked, so streams this relay handles stay unattributed.`

At startup sipnab asks the relay named by `--rtpengine-control` which calls are active. It does this to attribute media streams to calls.

- The value `{addr}` is not an IP address and port. `{e}` is the parse error.
- So sipnab asked nothing, and streams that relay handles stay unattributed.
- The capture still runs.

**What to do:** Give the relay's ng control port as numeric `IP:port`, for example `--rtpengine-control 127.0.0.1:22222`.

**Exit code:** None. sipnab logs the error, and the run continues.

### `--rtpengine-control {addr} is not an address and port ({e}); nothing is polled.`

The value of `--rtpengine-control` must be a literal IP address and port, such as `127.0.0.1:22222`. sipnab does not resolve host names. `{addr}` is the value as typed, and `{e}` is the parse error. Because the value did not parse, the statistics poller does not start. The rest of the run continues.

**What to do:** Give `--rtpengine-control` an IP address and port, for example `--rtpengine-control 127.0.0.1:22222`, using the relay's control (`ng`) port. An IPv6 address needs brackets, for example `[::1]:22222`.

**Exit code:** None. sipnab logs the error, and the run continues.

### `--rtpengine-control {addr} is not an address and port ({e}); nothing was asked.`

The `--rtpengine-control` value `{addr}` is not an IP address and port, so the relay statistics request (`--relay-stats`, `--relay-stats-call` or `--relay-stats-list`) or `--relay-holdings` asked nothing. `{e}` is the parse error.

**What to do:** Give the address as numeric `IP:port`, for example `--rtpengine-control 127.0.0.1:22222`.

**Exit code:** None for the statistics request: sipnab logs the error, and the run continues. 2 for `--relay-holdings`, which exits without answering.

### `{}: {} stepped backwards {} -> {} between polls; a cumulative counter cannot decrease, so the relay probably restarted (suspect). The counters below are since an unknown start.`

Between two `--relay-stats-interval` polls, a numeric counter that the relay reports went down.

- The first `{}` is `rtpengine at <addr>`.
- The second is the counter name.
- The last two are the previous and current values.
- Cumulative counters only increase. So sipnab marks the reading as suspect:
  - the relay may have restarted;
  - the counters that follow count from an unknown start.

**What to do:** Check whether the relay restarted at that time. Compare later readings with each other, not with readings before this line.

**Exit code:** None. This is a warning, and the run continues.

### `the relay statistics poll thread panicked`

The background thread that polls the relay for statistics stopped with an internal error (a panic). The rest of the run continues, and relay statistics from that thread are incomplete.

**What to do:** Report it as a sipnab issue, with the command line you used.

**Exit code:** None. This is a warning, and the run continues.

### `the rtpengine reconciler thread panicked`

When the TUI closed, sipnab found that the rtpengine reconciler thread had ended with a panic (an internal failure). That thread matches the media relay's view of calls with the sipnab view.

- sipnab's panic hook ends the whole process at the panic, with exit code 101 or a core dump.
- So this line appears only in a build or test that runs without that hook.

**What to do:** This is an internal failure in sipnab, not a setting. Report it with the command line you used and the log output.

**Exit code:** None. sipnab logs this warning during shutdown.

### `{}: this poll's round trip took {elapsed:.1?}, longer than the {}s interval; the polling cadence has slipped and is slower than requested.`

One relay statistics poll took longer than the `--relay-stats-interval`. The first `{}` is `rtpengine at <addr>`, `{elapsed:.1?}` is the round-trip time, and the second `{}` is the interval in seconds. Polls never overlap, so the next poll starts later, and readings arrive less often than you requested.

**What to do:** Increase `--relay-stats-interval` above the round-trip time shown, or check why the relay is slow to answer.

**Exit code:** None. This is a warning, and the run continues.

## TLS decryption and uprobes

### `A keylog producer only records keys for what it attached to. Check both halves of that: the TLS library — eCapture picks one by looking at curl, which need not be the one the SIP daemon maps, so pass --libssl with the path the daemon shows in /proc/<daemon-pid>/maps — and the process, since --pid pins it to a single worker while a forking daemon spreads connections across all of them. Give sipnab --keylog-watch so keys minted after it starts are read too.`

Explains why a key-log producer such as eCapture may have recorded no keys: it may have attached to a different TLS library or to a different process.

**What to do:**

- Pass the key-log producer the library that the SIP daemon maps (shown in `/proc/<daemon-pid>/maps`).
- Cover every worker process.
- Give sipnab `--keylog-watch`.

**Exit code:** None. This is a warning, and the run continues.

### `Cannot open keylog FIFO {}: {e}`

The `--keylog` path is a FIFO (named pipe), and sipnab could not open it for reading. `{}` is the path and `{e}` the operating system error (for example permission denied or no such file). The run continues without TLS secrets from that pipe.

**What to do:** Check that the FIFO exists and that the user starting sipnab can read it. sipnab opens it before dropping privileges, so the starting user's permissions apply.

**Exit code:** None. sipnab logs the error, and the run continues.

### `Capture the handshake: restart the connection while the capture is running, or capture continuously from before the connections you want to read.`

The remedy for a capture that missed the TLS handshake.

**What to do:** Restart the connection while the capture runs, or capture continuously from before the connections start.

**Exit code:** None. This is a warning, and the run continues.

### `Failed to load --dtls-keylog {keylog}: {e:#}`

In the TUI, sipnab could not load the key log named by `--dtls-keylog`.

- That file supplies keys for decrypting DTLS-SRTP media. DTLS-SRTP encrypts RTP, and its keys come from a DTLS handshake.
- `{keylog}` is the path.
- `{e:#}` is the reason with its causes. When sipnab could not read the file, it is `Loading DTLS keylog from`, followed by the path and the operating system's reason. Examples of the reason are `No such file or directory` or `Permission denied`.
- The TUI keeps running without DTLS-SRTP decryption.
- A headless run (`-N`) prints the same text and exits 1.

**What to do:** Correct the path or the file permissions, or point `--dtls-keylog` at an NSS key log file (the `SSLKEYLOGFILE` format).

**Exit code:** None in the TUI, where the run continues without DTLS-SRTP decryption. 1 in a headless run.

### `Failed to load --keylog {}: {e:#}`

sipnab could not read the TLS key log file named by `--keylog`.

- `{}` is that path.
- `{e:#}` is the reason with its full chain of causes. It includes the operating-system error, or the parse error for the file.
- A run that asked for decryption stops instead of continuing without it.

**What to do:** Check these:

- the path is correct;
- the file exists, and the user sipnab runs as can read it;
- its lines are in NSS SSLKEYLOGFILE format.

**Exit code:** 1.

### `Failed to load --srtp-keys {keyfile}: {e:#}`

In the TUI, sipnab could not load the SRTP master-key file named by `--srtp-keys`.

- `{keyfile}` is the path.
- `{e:#}` is the reason with its causes. When sipnab could not read the file, it is `Failed to read SRTP key file:`, followed by the path and the operating system's reason. Examples of the reason are `No such file or directory` or `Permission denied`.
- The TUI keeps running with no SRTP decryption context.
- A headless run (`-N`) prints the same text and exits 1.

**What to do:** Correct the path or the file permissions, or fix the file's contents so that sipnab accepts each key line. Without `--srtp-keys`, sipnab still decrypts with SDES keys it reads from SDP `a=crypto` lines.

**Exit code:** None in the TUI, where the run continues without SRTP decryption. 1 in a headless run.

### `Failed to load --tls-key {keyfile}: {e:#}`

sipnab could not load the RSA private key named by `--tls-key`. sipnab uses it to decrypt TLS 1.2 connections that use RSA key exchange.

- `{keyfile}` is the path.
- `{e:#}` is the reason with its causes. It is one of these:
  - when sipnab could not read the file: `reading TLS private key from`, followed by the path and the operating system's reason. Examples of the reason are `No such file or directory` or `Permission denied`;
  - a statement that the file is not a PKCS#1 or PKCS#8 PEM RSA private key.

**What to do:** Check these:

- the path is correct, and readable by the user sipnab runs as;
- the file is an RSA private key in PEM format. That is the text format whose first line names `RSA PRIVATE KEY` or `PRIVATE KEY`.

**Exit code:** 1.

### `--hep-tls-ca verifies the collector's certificate and does nothing without --hep-send-transport tls`

`--hep-tls-ca` names the certificate authority that sipnab uses to check the certificate of the HEP collector that `--hep-send` forwards to. HEP (Homer Encapsulation Protocol) is the format sipnab uses to forward captured packets. That check happens only on a TLS connection, and you did not set `--hep-send-transport` to `tls` (it defaults to UDP).

**What to do:** Add `--hep-send-transport tls` to forward over TLS, or remove `--hep-tls-ca`.

**Exit code:** 2.

### `--hep-tls-cert/--hep-tls-key are what a TLS listener presents and do nothing without --hep-listen-transport tls`

`--hep-tls-cert` and `--hep-tls-key` are the certificate and private key that the HEP listener (`--hep-listen`) presents to senders over TLS.

- You gave at least one of them.
- But you did not set `--hep-listen-transport` to `tls`. It defaults to UDP.
- So sipnab would use neither.

**What to do:** Add `--hep-listen-transport tls` to accept HEP over TLS, or remove `--hep-tls-cert` and `--hep-tls-key`.

**Exit code:** 2.

### `--hep-tls-extra-ca adds to the roots the collector's certificate is verified against and does nothing without --hep-send-transport tls`

`--hep-tls-extra-ca` adds certificate authorities (roots) to a set. sipnab uses that set to check the certificate of the HEP collector that `--hep-send` forwards to.

- That check happens only on a TLS connection.
- You did not set `--hep-send-transport` to `tls`. It defaults to UDP.

**What to do:** Add `--hep-send-transport tls` to forward over TLS, or remove `--hep-tls-extra-ca`.

**Exit code:** 2.

### `--keylog and --keylog-fd name different sources of the same secrets; pass one, not both`

`--keylog` reads TLS session secrets from a path. The secrets are a key log file in NSS `SSLKEYLOGFILE` format.

- `--keylog-fd` reads the same kind of secrets from an already-open file descriptor.
- You gave both. sipnab does not choose between them.

**What to do:** Keep one of the two flags and remove the other.

**Exit code:** 2.

### `--keylog-fd {fd} is not a readable descriptor: {e}`

sipnab could not duplicate the file descriptor number given to `--keylog-fd`.

- `{fd}` is that number.
- `{e}` is the operating system error. For example, a bad file descriptor when that number is not open in sipnab's process.
- The run continues without this keylog stream. So no TLS secrets arrive from it.

**What to do:**

- Start sipnab from a process that passes the descriptor open to it (not closed on exec).
- Give `--keylog-fd` the number of that descriptor.

Alternatively, name a keylog file or FIFO with `--keylog`.

**Exit code:** None. sipnab logs the error, and the run continues.

### `--keylog-fd must be a descriptor sipnab inherited, got {fd}`

`--keylog-fd` takes the number of a file descriptor (an open file handle) that the program starting sipnab left open for it. `{fd}` is the value you gave, which is negative, and no descriptor number is negative. This check refuses negative numbers only.

**What to do:** Pass the non-negative number of the descriptor that the starting program opened for sipnab, for example `--keylog-fd 3`. The command line accepts a negative value only in the form `--keylog-fd=-1`, because the parser reads a bare `-1` as a flag.

**Exit code:** 2.

### `--keylog-fd requires the 'tls' feature (not compiled in)`

`--keylog-fd` names an already-open file descriptor from which sipnab reads TLS key log lines (the secrets that let it decrypt TLS traffic). This sipnab build does not include TLS decryption support (the `tls` feature), so it cannot use the descriptor. sipnab refuses the run before it opens the capture.

**What to do:** Use a sipnab build that includes the `tls` feature, or remove `--keylog-fd`.

**Exit code:** 2.

### `--tls-key requires the 'tls' feature (not compiled in)`

`--tls-key` names a TLS private key that sipnab uses to decrypt TLS 1.2 sessions with RSA key exchange. This sipnab build does not include TLS decryption support (the `tls` feature). sipnab refuses the run before it opens the capture.

**What to do:** Use a sipnab build that includes the `tls` feature, or remove `--tls-key`.

**Exit code:** 2.

### `--keylog requires the 'tls' feature (not compiled in)`

`--keylog` names a TLS key log file (the `SSLKEYLOGFILE` format) that sipnab uses to decrypt TLS sessions. This sipnab build does not include TLS decryption support (the `tls` feature). sipnab refuses the run before it opens the capture.

**What to do:** Use a sipnab build that includes the `tls` feature, or remove `--keylog`.

**Exit code:** 2.

### `--keylog-watch requires the 'tls' feature (not compiled in)`

`--keylog-watch` makes sipnab read new lines from the TLS key log while the capture runs. This sipnab build does not include TLS decryption support (the `tls` feature). sipnab refuses the run before it opens the capture.

**What to do:** Use a sipnab build that includes the `tls` feature, or remove `--keylog-watch`.

**Exit code:** 2.

### `--srtp-keys requires the 'tls' feature (not compiled in)`

`--srtp-keys` names a file of SRTP master keys that sipnab uses to decrypt media. This sipnab build does not include TLS decryption support (the `tls` feature). sipnab refuses the run before it opens the capture.

**What to do:** Use a sipnab build that includes the `tls` feature, or remove `--srtp-keys`.

**Exit code:** 2.

### `--dtls-keylog requires the 'tls' feature (not compiled in)`

`--dtls-keylog` names a DTLS key log from which sipnab derives the SRTP keys of DTLS-SRTP calls. This sipnab build does not include TLS decryption support (the `tls` feature). sipnab refuses the run before it opens the capture.

**What to do:** Use a sipnab build that includes the `tls` feature, or remove `--dtls-keylog`.

**Exit code:** 2.

### `Keylog stream read failed: {e}`

The TLS key log can be a stream:

- `--keylog-watch`;
- `--keylog-fd`;
- or a key log that sipnab opened in the privileged startup window, such as a FIFO.

Then sipnab reads what the stream already holds before the first packet. That first read failed. `{e}` is the error. The run continues, and later polls of the same source still run.

**What to do:** Check that the user sipnab runs as can read the key log path or descriptor. Check that the producer is writing to it.

**Exit code:** None. This is a warning, and the run continues.

### `Key material is NOT locked into RAM: {reason}`

A warning: the run loads decryption keys, and sipnab could not lock its memory into RAM. So the operating system may write key material to swap.

- `{reason}` gives the cause.
  - On Linux, `mlockall` failed. Usually the memory-lock limit `RLIMIT_MEMLOCK` is too low.
  - On other systems, the reason says that sipnab locks memory on Linux only.
- The run continues.

**What to do:** Raise the memory-lock limit, with `ulimit -l` or `LimitMEMLOCK=` in the systemd unit, as the reason states.

**Exit code:** None. This is a warning, and the run continues.

### `manual SRTP keys loaded from {keyfile} — use only in test environments`

`--srtp-keys <file>` loaded SRTP (encrypted RTP) keys from a file you supplied by hand. `{keyfile}` is that path. sipnab prints this warning on every such run, including at `-q`, because manually supplied key material is a testing aid.

**What to do:** If you intend this, you need to do nothing. On production traffic, omit `--srtp-keys`. sipnab still picks up keys from SDP `a=crypto` lines without it.

**Exit code:** None. This is a warning, and the run continues.

### `\n{unreachable} of these cannot be reached from sipnab's mount namespace and would NOT be captured. They are most likely inside containers; run as root.`

A warning after the `--uprobe-list` table: sipnab cannot open `{unreachable}` of the listed libraries at a path whose file matches the mapped library.

- sipnab compares the inode, through `/proc/<pid>/root` and then the plain path.
- The table marks them `(UNREACHABLE)`, and sipnab would not probe them.
- Libraries inside containers are the usual case.

**What to do:** Run sipnab as root so it can reach the libraries through `/proc/<pid>/root`.

**Exit code:** 0. This is a warning, and sipnab still prints the listing.

### `--uprobe-library {path}: no such file, so a capture could not probe it`

`--uprobe-list` with `--uprobe-library` lists the named libraries, the ones a capture would probe, instead of discovering them. `{path}` names no file. The table marks it `(MISSING)`.

**What to do:** Give the path as sipnab sees it. For a library inside a container, that is `/proc/<pid>/root/` followed by the path inside the container.

**Exit code:** 1, after the table prints.

### `No TLS library is mapped by any process sipnab can see.\nEither nothing here uses OpenSSL or wolfSSL, or sipnab cannot read\n/proc/<pid>/maps — try again as root.`

`--uprobe-list` found no process mapping a TLS library sipnab can probe (OpenSSL or wolfSSL). It reads `/proc/<pid>/maps` for each process, and it does not see a process whose map it cannot read. When the command line includes `--uprobe-flavor`, sipnab counts only libraries of the named flavors.

**What to do:**

- Run `sipnab --uprobe-list` as root, so that every process's map is readable.
- Check that the program you want to observe is running, and uses OpenSSL or wolfSSL.
- Remove `--uprobe-flavor` to count both flavors.

**Exit code:** 1.

### `` Or skip the external extractor: `sudo sipnab --uprobe-list` reports what each process maps, and `sudo sipnab -N --uprobe-tls` probes every mapped TLS library itself, with no --libssl to choose and no keylog. ``

Printed with the list of mapped libraries. sipnab can read the TLS traffic itself with uprobes (probes that sipnab attaches to functions in the TLS library).

**What to do:** Run `sudo sipnab --uprobe-list` to see what each process maps, or run `sudo sipnab -N --uprobe-tls`.

**Exit code:** None. This is a warning, and the run continues.

### `--pcap-export-mode decrypted requires the 'tls' feature (not compiled in): use raw for original packets without keys`

`--pcap-export-mode decrypted` writes TLS traffic after decryption, which needs the `tls` Cargo feature (a build-time option). This sipnab binary does not include that feature. `raw` writes the original packets as captured.

**What to do:** Use `--pcap-export-mode raw`, or use a sipnab binary built with the `tls` feature (`--features tls` or `--features full`).

**Exit code:** 2.

### `Restart the connection while the capture is running — bounce the far end, or the daemon — so the stream is captured from its first record.`

The remedy for a capture that joined connections already running.

**What to do:** Restart the connection (bounce the far end, or the daemon) while the capture runs.

**Exit code:** None. This is a warning, and the run continues.

### `sipnab could not decrypt {unread} TLS application-data record(s): it holds no key material for any session in this capture, so this run says nothing about what that traffic contained.`

sipnab holds no key material for any TLS session in the capture. So `{unread}` application-data records went unread. The run says nothing about their contents.

**What to do:** Read the lines that follow.

**Exit code:** None. This is a warning, and the run continues.

### `sipnab discarded {} TLS record(s) held from before a key arrived: the late-decrypt hold is bounded ({} MiB total, {} record(s) per direction, {}s), and it filled before any key matched them. Start the key source before the capture, or expect the first message of a call to be missing.`

sipnab holds TLS records that arrive before their key, so that it can decrypt them later, and that hold filled up. The first number is how many records sipnab discarded. The others are the hold's limits: total MiB, records per direction, and seconds.

**What to do:** Start the key source before the capture, or expect the first message of a call to be missing.

**Exit code:** None. This is a warning, and the run continues.

### `sipnab holds keys for {} TLS session(s) and could not decrypt any of the {} application-data record(s) it saw.`

sipnab holds keys for the first number of TLS sessions and could not decrypt any of the second number of records.

**What to do:** Read the next two lines.

**Exit code:** None. This is a warning, and the run continues.

### `sipnab loaded {} keylog line(s) and built no session from any of them, so the {} TLS application-data record(s) in this capture went unread.`

sipnab loaded the first number of key-log lines. It could not build a TLS session from any of them. So the second number of TLS application-data records went unread.

**What to do:** Read the two lines that follow.

**Exit code:** None. This is a warning, and the run continues.

### `The handshake is missing. A TLS 1.2 key log gives the master secret; the server random and cipher suite that expand it into record keys are in the ServerHello, and a capture that started after the connection did never saw one. Nothing later in the capture can supply them.`

Follows the line above. For TLS 1.2, the session keys also need the server random value and the cipher suite from the `ServerHello` message. This capture started after the handshake.

**What to do:** Capture the handshake, as the next line says.

**Exit code:** None. This is a warning, and the run continues.

### `The usual cause is a capture that began against connections which were already running. A TLS record is numbered by a counter both endpoints keep privately, nothing on the wire carries it, and sipnab searches only the first {} records of a stream for it — a trunk that has been up for hours is far past that. Capturing the handshake does not help; the counter depends on how many records have gone by since.`

A TLS record's sequence number is not on the wire. sipnab searches only the first `{}` records of a stream for it. sipnab therefore cannot decrypt a capture that joined long-running connections.

**What to do:** Restart the connection while the capture runs, as the next line says.

**Exit code:** None. This is a warning, and the run continues.

### `` This host maps {}. Pass the one the SIP daemon uses, e.g. `ecapture tls -m keylog -k keys.log --libssl={}`. ``

Lists the TLS library paths that processes on this host map. The second `{}` is the first of them, shown in an example eCapture command.

**What to do:** Pass the library that the SIP daemon uses to the key-log producer.

**Exit code:** None. This is a warning, and the run continues.

### `TLS late decrypt: {} record(s) opened only after the capture ended -- their keys arrived too late to place the messages in this run. Re-read the saved capture with the same keylog to see them.`

sipnab held some TLS records because their keys had not arrived. At the end of the capture, the late keys opened them.

- That came too late for this run's analysis to include them.
- `{}` is the number of records.
- sipnab holds records when the key log can grow during the run (`--keylog-watch` or `--keylog-fd`).

**What to do:** Read the saved capture again with `-I <file>` and the same `--keylog`. On that run the keys are present from the start.

**Exit code:** None. This is a warning, and the run continues.

### `{} TLS record(s) were still waiting when the run ended: no key ever arrived for them. Nothing was discarded and starting the capture earlier would not have helped -- the key source never produced those secrets.`

`{}` TLS records were still waiting when the run ended, because no key for them ever arrived. sipnab discarded nothing.

**What to do:** Starting the capture earlier does not help. Check that the key source produces secrets for these connections.

**Exit code:** None. This is a warning, and the run continues.

### `` --uprobe-list needs Linux kernel uprobes and a sipnab built with the `native` feature ``

`--uprobe-list` lists the TLS libraries that sipnab could attach uprobes to. Uprobes are Linux kernel hooks on functions inside a running program's TLS library. sipnab uses them to read decrypted traffic.

This build runs on a system without Linux uprobes. Or its build did not include the `native` feature.

**What to do:** Run a sipnab built with the `native` feature on Linux.

**Exit code:** 1.

## vCon export, fetch and forwarding

### `'{url}': a base URL with a query cannot take the read path; give a template holding {{uuid}}`

You gave the fetcher a base URL with a `?query`, and a store kind that builds the read address by adding a path (`vcon-store`, `conserver`, `vcon-mcp`).

- sipnab cannot add a path after a query.
- `{url}` is the URL as sipnab parsed it.
- The line starts with `--vcon-fetch-url` or `[vcon_fetch] url`.

**What to do:** Do one of these:

- Give the full read URL as a template, with `{uuid}` where the uuid goes. For example, `https://host/api/vcon/{uuid}?x=1`.
- Remove the query from the base URL.

**Exit code:** 2 when the URL came from `--vcon-fetch-url`, and 1 when it came from `[vcon_fetch] url`.

### `{AUTH_INLINE} and {AUTH_FLAG} both name the credential; give one`

You gave the credential both inline (`--vcon-forward-auth` or `SIPNAB_VCON_FORWARD_AUTH`) and as a file (`--vcon-forward-auth-file`). The forwarder takes one source.

The flag definition declares the two in conflict. So the command-line parser refuses the pair with its own message before this check runs.

**What to do:** Keep one source. Unset `SIPNAB_VCON_FORWARD_AUTH` and drop `--vcon-forward-auth`, or drop `--vcon-forward-auth-file`.

**Exit code:** 2.

### `{AUTH_INLINE} and {AUTH_KEY} both name the credential; give one, or name another file with {AUTH_FLAG}, which replaces the key`

You gave the credential inline (`--vcon-forward-auth` or `SIPNAB_VCON_FORWARD_AUTH`), and the config file also names a credential file with `[vcon_forward] auth_file`. The forwarder takes one source.

**What to do:** Unset `SIPNAB_VCON_FORWARD_AUTH` and drop `--vcon-forward-auth`, or remove `[vcon_forward] auth_file` from the config file. A `--vcon-forward-auth-file` on the command line replaces the config key.

**Exit code:** 2.

### `{url} answered {status} ({})`

The store answered with an unexpected HTTP status (`{status}`). `{}` is the start of its answer.

**What to do:** Read the store's answer and check its logs.

**Exit code:** 1.

### `{url} answered {}: the store refused the credential or this client ({}); nothing more is fetched`

The store answered 401 or 403: it refused the credential or this client. The first `{}` is the status, and the second is the start of the store's answer. sipnab fetches no further `uuid`.

**What to do:** Check the credential that you gave with the `--vcon-fetch` auth settings.

**Exit code:** 3.

### `{name}: {method} {url} answered {status}; will retry`

The store answered container `{name}` with a status that the forwarder retries: any 5xx, a 3xx, or a 2xx outside the range that the store kind counts as delivered. `{method}` is POST or PUT, `{url}` is where the forwarder sent it, and `{status}` is the status code.

**What to do:** For 5xx answers, check the state of the store. For a 3xx answer, set `--vcon-forward-url` to the address the store redirects to, because the forwarder does not follow redirects.

**Exit code:** None. This is a warning. The container stays in the spool, and the forwarder retries it with a delay that doubles each time. With `--vcon-forward-once`, the run exits 1.

### `'{shown}': a URL cannot hold whitespace`

The vCon store URL contains a space, tab, line break or other control character. sipnab refuses it.

- A vCon is a JSON container for one conversation. The forwarder sends vCons to a store, and the fetcher reads them back.
- The line starts with the setting the URL came from, for example `--vcon-forward-url` or `[vcon_fetch] url`.
- `{shown}` is the URL as written, with any `user:password@` part replaced by `[redacted]`.

**What to do:** Remove the whitespace from the URL. Percent-encode a space that belongs in the path or query as `%20`.

**Exit code:**

- 2 when the URL came from a flag (`--vcon-forward-url`, `--vcon-forward-replace-url` or `--vcon-fetch-url`);
- 1 when it came from the config file (`[vcon_forward] url`, `[vcon_forward] replace_url` or `[vcon_fetch] url`).

### `'{shown}': a URL sent to a store has no fragment`

The vCon store URL contains a `#`. sipnab refuses any URL with a `#` in it, because an HTTP client never sends a fragment to a server. The line starts with the setting the URL came from, for example `--vcon-forward-url` or `[vcon_fetch] url`. `{shown}` is the URL as written, with any `user:password@` part replaced by `[redacted]`.

**What to do:** Remove the `#` and everything after it from the URL. If a `#` belongs in the path or query, percent-encode it as `%23`.

**Exit code:**

- 2 when the URL came from a flag (`--vcon-forward-url`, `--vcon-forward-replace-url` or `--vcon-fetch-url`);
- 1 when it came from the config file (`[vcon_forward] url`, `[vcon_forward] replace_url` or `[vcon_fetch] url`).

### `Call-ID '{call_id}' not found in tracked dialogs, so there is no dialog to export. --report lists the Call-IDs this run holds.`

`--export-vcon <CALL-ID>` asks for one call as a vCon container (a JSON format for a call record). This run tracked no dialog with that exact Call-ID. So sipnab exports nothing.

**What to do:** Run with `--report` to list the Call-IDs this run holds, then pass one of them exactly. The match is exact. `--markdown` shows full Call-IDs in the table.

**Exit code:** 1.

### `{} cannot be used with {export} on a live capture. A live run writes each call's container shortly after the call ends, and a run stopped by a signal writes nothing more, so the redaction map and tombstones this run would write at its end are never written. Use {} with -I on a saved capture, which always runs to its end`

The flags listed in the first `{}` write their output when a run ends. They come from `--redact`, `--redact-map` and `--content-deny-tombstone`.

- `{export}` is `--export-vcon` or `--export-vcon-when`.
- On a live capture (no `-I`), sipnab writes each vCon container shortly after its call ends.
- A live run that a signal stops writes nothing more.
- So this run would never write the redaction map and tombstones.
- The second `{}` is `it` or `them`.

**What to do:** Do one of these:

- Run the export with `-I` on a saved capture file. That always runs to its end.
- Remove the listed flags from the live run.

**Exit code:** 2.

### `cannot create --redact-map '{}': {e}`

sipnab could not create the `--redact-map` file. The text after the path is the operating system's reason.

**What to do:** Check that the directory exists and that the user sipnab runs as can write to it.

**Exit code:** 1.

### `{name}: cannot read it: {e}; will retry`

The forwarder could not read container `{name}` from the spool, for a reason other than a missing file. `{e}` is the operating system error. The forwarder opens the file without following a symbolic link.

**What to do:** Give the sipnab user read permission on the files in the spool.

**Exit code:** None. This is a warning. The container stays in the spool, and the forwarder retries it with a delay that doubles each time. With `--vcon-forward-once`, the run exits 1.

### `cannot read --redact-key-file '{}': {e}`

`--redact-key-file` names a file that sipnab could not read, so sipnab wrote no redacted vCon. The text after the path is the operating system's reason.

**What to do:** Check the path, and check that the user sipnab runs as can read the file.

**Exit code:** 1.

### `cannot read the spool '{}': {e}`

The forwarder could not list the files in its spool directory at the start of a pass, so that pass sends nothing. `{}` is the spool path, and `{e}` is the operating system error. The forwarder tries again after `--vcon-forward-interval`.

**What to do:** Give the sipnab user read and execute permission on the spool directory, and check that it still exists.

**Exit code:** None. This is a warning, and the run continues. With `--vcon-forward-once`, the run exits 0.

### `Could not create the vCon directory '{}': {e}. Nothing was exported.`

sipnab could not create the directory named by `--export-vcon-dir`. The quoted path is that directory, and the text after it is the operating system's reason. sipnab wrote no vCon file.

**What to do:** Check that the parent directory exists, and that the user sipnab runs as can write to it. Or name a different directory.

**Exit code:** 1.

### `{name}: could not move it to '{}': {e}`

After the store's answer, the forwarder could not rename container `{name}` into the delivered or failed directory. `{}` is that directory, and `{e}` is the operating system error. The container stays in the spool, and the forwarder sends it again on the next pass.

**What to do:** Give the sipnab user write permission on the spool and on the directory the message names (`--vcon-forward-done` or `--vcon-forward-failed`).

**Exit code:** None. sipnab logs the error, and the run continues. With `--vcon-forward-once`, the run exits 1.

### `{name}: could not return the rewritten container to the spool: {e}`

Something rewrote container `{name}` in the spool while the forwarder was sending it.

- The forwarder had already moved the file into the delivered or failed directory.
- It found that the file was the newer version, which the store has not received.
- Linking it back into the spool failed.
- `{e}` is the operating system error.
- The newer version stays in the delivered or failed directory. The forwarder does not send it.

**What to do:**

- Move `{name}` from the delivered or failed directory back into the spool, so that the forwarder sends it.
- Give the sipnab user write permission on the spool.

**Exit code:** None. sipnab logs the error, and the run continues. With `--vcon-forward-once`, the run exits 1.

### `{name}: could not write {record_name}: {e}`

The forwarder moved container `{name}` to the failed directory. But it could not write its failure record `{record_name}`.

- The record is `<name>.error.json`. It holds the store's answer or the reason.
- `{e}` is the operating system error.

**What to do:** Give the sipnab user write permission on the failed directory, and check that the filesystem has free space.

**Exit code:** None. sipnab logs the error, and the run continues. With `--vcon-forward-once`, the run exits 1.

### `Could not write '{}': {e}. {written} container(s) were written before this.`

sipnab could not write the vCon file at the quoted path.

- The text after the path is the operating system's reason.
- `{written}` is how many vCon files this run had already written before it stopped.

**What to do:** Check free space and write permission in the `--export-vcon-dir` directory, then run the export again.

**Exit code:** 1.

### `Could not write the vCon for Call-ID '{call_id}' to '{}': {e}. Nothing was exported.`

sipnab built the vCon container for `{call_id}` but could not write it to the `--vcon-out` path `'{}'`. `{e}` is the operating system's error. sipnab writes the file atomically (it renames a temporary file into place), so a file already at that path stays unchanged.

**What to do:** Check that the directory of the `--vcon-out` path exists, and that the user sipnab runs as can write to it. Or choose another path.

Without `--vcon-out`, sipnab writes the container to standard output.

**Exit code:** 1.

### `{uuid}: {} exists; not fetched. --vcon-fetch-overwrite replaces it`

`--vcon-fetch` did not fetch `{uuid}` because the output file (the `{}`) already exists.

**What to do:** Pass `--vcon-fetch-overwrite` to replace it, or move the file.

**Exit code:** 1.

### `--export-vcon-when is not a valid filter expression: {e}`

sipnab could not parse the expression given to `--export-vcon-when`. It uses the same filter language and alias expansion as `--filter`, and sipnab parses it before the capture opens. `{e}` is the parser's reason.

**What to do:** Correct the expression so that it is valid `--filter` syntax. An expression that works with `--filter` works here.

**Exit code:** 2.

### `--export-vcon-when needs --export-vcon-dir. Nothing was exported.`

A run that selects calls with `--export-vcon-when` also needs `--export-vcon-dir` to name the directory for the vCon files. You did not give it, so sipnab wrote no vCon file.

**What to do:** Add `--export-vcon-dir <DIR>` to the command.

**Exit code:** 1.

### `` gives `{name}` a value holding a control character ``

The credential line names header `{name}`, but its value contains a control character. For example, a tab or a carriage return inside the value. An HTTP header cannot carry one.

- sipnab does not print the value.
- The line starts with the source: `--vcon-forward-auth (or SIPNAB_VCON_FORWARD_AUTH)`, or the auth file setting and path.
- The forwarder and the fetcher read one header line, `Header-Name: value`.
- When `--vcon-forward-kind` or `--vcon-fetch-kind` is `vcon-store`, `conserver` or `vcon-mcp`, sipnab uses a line that fails this check as a bare key instead.
- You therefore see this refusal only with the `generic` kind (the default).

**What to do:** Rewrite the credential as one line, `Header-Name: value`, with no control characters in the value.

**Exit code:** 2 when the credential came from `--vcon-forward-auth`, `SIPNAB_VCON_FORWARD_AUTH`, `--vcon-forward-auth-file` or `--vcon-fetch-auth-file`, and 1 when `[vcon_forward] auth_file` or `[vcon_fetch] auth_file` named the file.

### `` gives `{name}` no value ``

The credential line names header `{name}`, but has nothing after the colon.

- The line starts with the source: `--vcon-forward-auth (or SIPNAB_VCON_FORWARD_AUTH)`, or the auth file setting and path.
- The forwarder and the fetcher read one header line, `Header-Name: value`.
- When `--vcon-forward-kind` or `--vcon-fetch-kind` is `vcon-store`, `conserver` or `vcon-mcp`, sipnab uses a line that fails this check as a bare key instead.
- You therefore see this refusal only with the `generic` kind (the default).

**What to do:** Put the credential after the colon, for example `Authorization: Bearer <token>`.

**Exit code:** 2 when the credential came from `--vcon-forward-auth`, `SIPNAB_VCON_FORWARD_AUTH`, `--vcon-forward-auth-file` or `--vcon-fetch-auth-file`, and 1 when `[vcon_forward] auth_file` or `[vcon_fetch] auth_file` named the file.

### `'{}' has no {{uuid}} to fill in`

The forwarder's replace URL holds no `{uuid}`.

- When the store answers 409, it already holds that uuid. The forwarder then sends the container with PUT to the replace URL, with the container's uuid filled in.
- `{}` is the template as written, with any `user:password@` part replaced by `[redacted]`.
- The line starts with `--vcon-forward-replace-url` or `[vcon_forward] replace_url`.

**What to do:** Write `{uuid}` in the replace URL where the uuid goes, for example `https://store.example.com/v1/vcons/{uuid}`.

**Exit code:** 2 when the URL came from `--vcon-forward-replace-url`, and 1 when it came from `[vcon_forward] replace_url`.

### `{flag} is a vCon fetcher setting and needs --vcon-fetch`

`{flag}` is the first option you gave that only the vCon fetcher reads. That is a fetcher option such as `--vcon-fetch-url` or `--vcon-fetch-out`.

- But you did not give `--vcon-fetch`. So the fetcher does not run.
- vCon is a JSON format for a recorded conversation.

**What to do:** Add `--vcon-fetch UUID` to fetch a vCon, or remove the named option.

**Exit code:** 2.

### `{flag} is a vCon forwarder setting and needs --vcon-forward`

`{flag}` is the first option you gave that only the vCon forwarder reads. That is a forwarder option such as `--vcon-forward-url` or `--vcon-forward-once`.

- But you did not give `--vcon-forward`. So the forwarder does not run.
- This check skips `--vcon-forward-auth`.
- vCon is a JSON format for a recorded conversation.

**What to do:** Add `--vcon-forward` to run the forwarder, or remove the named option.

**Exit code:** 2.

### `{uuid:?} is not a uuid`

The value you gave `--vcon-fetch` is not a `uuid`, so sipnab requested nothing for it.

**What to do:** Pass the vCon's `uuid`.

**Exit code:** 1.

### `{flag} '{}' is on another filesystem from the spool; a move must be a rename`

The delivered or failed directory is on a different filesystem from the spool. The forwarder moves a container out of the spool by renaming it, which works only within one filesystem. `{flag}` is `--vcon-forward-done ([vcon_forward] done)` or `--vcon-forward-failed ([vcon_forward] failed)`, and `{}` is the directory.

**What to do:** Choose a delivered and a failed directory on the spool's filesystem. Or leave both unset to use `delivered` and `failed` inside the spool.

**Exit code:** 2.

### `{value} is out of range: give a whole number from {} to {}`

A whole-number setting of the vCon forwarder or fetcher is outside its range.

- `{value}` is the number given.
- The two `{}` are the smallest and largest accepted values.
- Ranges:
  - interval 1-3600 and timeout 1-600 seconds for the forwarder;
  - timeout 1-600 for the fetcher;
  - 1-4294967295 for the back-off, response-head, error-body and size settings.
- For a flag (such as `--vcon-forward-interval`), the argument parser reports the error.
- For a key, sipnab prefixes the section and the key. `interval = 0` under `[vcon_forward]` reads `invalid config value: [vcon_forward] interval: 0 is out of range: give a whole number from 1 to 3600`, and `timeout = 0` under `[vcon_fetch]` reads `invalid config value: [vcon_fetch] timeout: 0 is out of range: give a whole number from 1 to 600`.

**What to do:** Give a whole number inside the range the message states.

**Exit code:** 2 for a flag, and 1 for a `[vcon_forward]` or `[vcon_fetch]` key.

### `{endpoint} is plain http to another machine: the auth header and every container cross the network unencrypted. Use https:// for anything but loopback`

The store URL `{endpoint}` uses plain `http` to a host that is not this machine. So the auth header and every container cross the network unencrypted.

**What to do:** Use an `https://` URL for anything but loopback.

**Exit code:** None. This is a warning, and the run continues.

### `{flag} '{}' is the spool itself`

The delivered or failed directory is the spool directory itself. `{flag}` is `--vcon-forward-done ([vcon_forward] done)` or `--vcon-forward-failed ([vcon_forward] failed)`, and `{}` is the directory.

**What to do:** Name a different directory on the spool's filesystem. Or leave the setting unset to use `delivered` or `failed` inside the spool.

**Exit code:** 2.

### `{from} '{shown}': larger than {MAX_AUTH_FILE} bytes; it holds one line`

The credential file is larger than 8192 bytes. It must hold one line. `{from}` is the setting that named the file (`--vcon-forward-auth-file`, `[vcon_forward] auth_file`, `--vcon-fetch-auth-file` or `[vcon_fetch] auth_file`). `{shown}` is its path, and `{MAX_AUTH_FILE}` is 8192.

**What to do:** Reduce the file to the one credential line, `Header-Name: value`. Or reduce it to the bare key, for a store kind that supplies the header.

**Exit code:** 2 when a flag named the file (`--vcon-forward-auth-file` or `--vcon-fetch-auth-file`), and 1 when `[vcon_forward] auth_file` or `[vcon_fetch] auth_file` named it.

### `line {}: {line:?} is not a uuid (1 to 64 characters, each a letter, a digit or '-')`

`--vcon-fetch -` reads uuids from standard input, one per line, and line `{}` is not a uuid. `{line:?}` is that line, quoted. A uuid here is 1 to 64 characters, each a letter, a digit or `-`. sipnab skips blank lines and lines that start with `#`. The message starts with `--vcon-fetch -: `.

**What to do:** Correct or remove the line the message names, or comment it out with `#`.

**Exit code:** 2.

### `` names `{name}`, which the forwarder writes itself; name the header that authenticates ``

The credential line names header `{name}`. The forwarder writes this header itself on every request (`Host`, `Content-Type`, `Content-Length`, `Transfer-Encoding`, `Connection`, `User-Agent` or `Expect`).

- The line starts with the source: `--vcon-forward-auth (or SIPNAB_VCON_FORWARD_AUTH)`, or the auth file setting and path.
- The forwarder and the fetcher read one header line, `Header-Name: value`.
- When `--vcon-forward-kind` or `--vcon-fetch-kind` is `vcon-store`, `conserver` or `vcon-mcp`, sipnab uses a line that fails this check as a bare key instead.
- You therefore see this refusal only with the `generic` kind (the default).

**What to do:** Name the header the store authenticates with, for example `Authorization: Bearer <token>`.

**Exit code:** 2 when the credential came from `--vcon-forward-auth`, `SIPNAB_VCON_FORWARD_AUTH`, `--vcon-forward-auth-file` or `--vcon-fetch-auth-file`, and 1 when `[vcon_forward] auth_file` or `[vcon_fetch] auth_file` named the file.

### `{url}: {problem}; nothing was written`

The store's answer from `{url}` was incomplete. `{problem}` says how. sipnab wrote nothing.

**What to do:** Retry, and check the store and the network path.

**Exit code:** 1.

### `{url}: {e}; nothing was written`

sipnab could not take the vCon out of the store's answer from `{url}`. `{e}` is the reason. sipnab wrote nothing.

**What to do:** Check that the store kind setting matches the store.

**Exit code:** 1.

### `{name}: {endpoint} not reached: {e}; will retry`

The PUT of container `{name}` to the replace URL failed before the forwarder could read a status. The forwarder sent the PUT after a 409.

- `{endpoint}` is the filled-in replace URL.
- `{e}` is the reason:
  - no address;
  - no connection;
  - a TLS failure;
  - an answer the forwarder could not read (closed early, not HTTP, or headers over `--vcon-forward-max-response-head`).

**What to do:** Check that the host of the replace URL is reachable and serves HTTP or HTTPS. If `{e}` names the header limit, raise `--vcon-forward-max-response-head`.

**Exit code:** None. This is a warning. The container stays in the spool, and the forwarder retries it with a delay that doubles each time. With `--vcon-forward-once`, the run exits 1.

### `{name}: {url} not reached: {e}; will retry`

The POST of container `{name}` to the store failed before the forwarder could read a status.

- `{url}` is the store URL.
- `{e}` is the reason:
  - the host does not resolve;
  - no connection within `--vcon-forward-timeout`;
  - a TLS failure;
  - an answer the forwarder could not read (closed early, not HTTP, or headers over `--vcon-forward-max-response-head`).

**What to do:**

- Check that the store's host and port are reachable from this machine.
- Check that the scheme (`http://` or `https://`) matches the store.
- If `{e}` names the header limit, raise `--vcon-forward-max-response-head`.

**Exit code:** None. This is a warning. The container stays in the spool, and the forwarder retries it with a delay that doubles each time. With `--vcon-forward-once`, the run exits 1.

### `'{shown}': put credentials in {setting}, not in the URL`

The URL holds a user name or password before an `@`, as in `https://user:secret@vcon.example.com/v1/vcons`.

- sipnab refuses it, so that the credential stays out of logs.
- The line starts with the setting the URL came from, for example `--vcon-forward-url` or `[vcon_fetch] url`.
- `{shown}` is the URL as written, with any `user:password@` part replaced by `[redacted]`.
- `{setting}` is where the credential for that URL goes instead:
  - `--vcon-forward-auth-file` for the forwarder's store URL and replace URL;
  - `--vcon-forward-scitt-auth-file` for its transparency service URL;
  - `--vcon-fetch-auth-file` for the fetcher's store URL;
  - `[[vcon.enrich]] auth_file` for an enrichment service URL.

**What to do:** Remove the `user:password@` part from the URL, and put the credential in the file `{setting}` names. The forwarder also reads it from `SIPNAB_VCON_FORWARD_AUTH`, and each flag has a config key: `[vcon_forward] auth_file`, `[vcon_forward] scitt_auth_file` and `[vcon_fetch] auth_file`.

**Exit code:**

- 2 when the URL came from a flag (`--vcon-forward-url`, `--vcon-forward-replace-url`, `--vcon-forward-scitt-url` or `--vcon-fetch-url`);
- 1 when it came from the config file (`[vcon_forward] url`, `[vcon_forward] replace_url`, `[vcon_forward] scitt_url`, `[vcon_fetch] url` or `[[vcon.enrich]] url`).

### `'{shown}': a URL {client} reads cannot hold credentials`

A URL sipnab reads without credentials holds a user name or password before an `@`. These are the URLs a vCon names (an `x5u` certificate chain, a dialog's audio `url`) and the `Location` a transparency service answers with. `{client}` is `sipnab`, and `{shown}` is the URL with its `user:password@` part replaced by `[redacted]`. sipnab sends no request to the URL.

**What to do:** Remove the `user:password@` part from the URL at its source. sipnab sends no credential to these URLs.

**Exit code:** None of its own. The message is the reason inside the message about that URL:

- for an `x5u` certificate chain: `x5u {url:?}: '{shown}': a URL sipnab reads cannot hold credentials`;
- for a dialog's audio `url`: `url '{shown}': a URL sipnab reads cannot hold credentials`;
- for a `Location`: `not polled: the Location {location:?} is not on the transparency service's origin {origin} ('{shown}': a URL sipnab reads cannot hold credentials)`, where `{origin}` is the scheme, host and port of the service's URL.

### `` --redact acts on the vCon exporter, which needs the 'vcon' Cargo feature this build does not carry. Rebuild with --features vcon (or --features full); `sipnab --version` lists the features a binary was built with ``

`--redact` changes the content of the vCon containers that sipnab exports. vCon is a JSON format for a recorded conversation. The exporter is part of the `vcon` Cargo feature (a build-time option), and this binary does not include that feature.

**What to do:** Use a sipnab binary built with `--features vcon` or `--features full`. `sipnab --version` lists the Cargo features that a binary includes.

**Exit code:** 2.

### `--redact-map '{}' already exists and sipnab will not write over it. That file may be the only way back from tokens already sent somewhere`

`--redact-map` names the file where sipnab writes a table. The table maps each redaction token back to the original value.

- A file (or link) already exists at that path.
- sipnab refuses to replace it. It may be the only way to reverse tokens in containers that an earlier run exported.
- `'{}'` is the path.
- With `--export-vcon <CALL-ID>`, the refusal comes before sipnab writes the container. So sipnab exports nothing.
- With `--export-vcon-when`, sipnab has already written the containers to `--export-vcon-dir` when the refusal happens.

**What to do:** Pass `--redact-map` a path that does not exist yet, or move the existing file elsewhere first.

**Exit code:** 1.

### `--redact needs a key and none was supplied, so sipnab drew one from the operating system and could not: {e}. There is no weaker fallback: a guessable key makes every token in the export reversible by anyone holding a phone book. Pass --redact-key-file, or fix the entropy source`

You gave `--redact` without `--redact-key-file`, so sipnab asked the operating system for a random key, and the request failed. sipnab does not fall back to a weaker key, so it wrote no redacted vCon.

**What to do:** Pass `--redact-key-file` with a key file, or fix the operating system's random-number source.

**Exit code:** 1.

### `--redact rewrites an EXPORTED container and this run exports none. Pair it with --export-vcon, --export-vcon-when or a [[vcon.rule]], or drop it — a run that accepted --redact and wrote nothing redacted would read as a redacted capture`

`--redact` acts on the vCon containers that a run exports. This run has none of these:

- `--export-vcon`;
- `--export-vcon-when`;
- a `[[vcon.rule]]` in its config file.

So `--redact` has nothing to act on. vCon is a JSON format for a recorded conversation.

**What to do:** Add `--export-vcon CALL-ID`, `--export-vcon-when` (with `--export-vcon-dir`) or a [`[[vcon.rule]]`](vcon.md#write-calls-by-rule), or remove `--redact`.

**Exit code:** 2.

### `refused {name}: {method} {url} answered {}; moved to '{}' beside {record_name}`

The store answered with a 4xx status that a retry does not change. So the forwarder moved the container to the failed directory.

- Such a status is any 4xx except 401 and 403, and except 409 when you set a replace URL.
- `{name}` is the container file.
- `{method}` is POST or PUT.
- `{url}` is where the forwarder sent it.
- The first `{}` is the status. The second is the failed directory.
- `{record_name}` is `<name>.error.json`. It holds the store's answer with the credential removed.

**What to do:**

- Read `<name>.error.json` for the store's reason.
- Correct the container or the forwarder settings. For example, `--vcon-forward-url`, `--vcon-forward-kind`, or `--vcon-forward-replace-url` for a 409.
- Move the container back into the spool to send it again.

**Exit code:** None. This is a warning, and the run continues. With `--vcon-forward-once`, the run exits 1.

### `refused {name}: not sent: {reason} Moved to '{}' beside {record_name}`

The store answered 409 (it already holds this uuid), and you set a replace URL. But the forwarder could not build the PUT request. The forwarder moved the container to the failed directory without sending it.

- `{name}` is the container file.
- `{reason}` says why:
  - the container is not JSON;
  - it has no `uuid`;
  - its `uuid` is not 1 to 64 letters, digits or `-`;
  - the filled-in replace URL does not parse.
- `{}` is the failed directory.
- `{record_name}` is `<name>.error.json`. It holds the same reason.

**What to do:**

- Read `<name>.error.json` in the failed directory.
- Correct the container or the replace URL (`--vcon-forward-replace-url`).
- Move the container back into the spool to send it again.

**Exit code:** None. This is a warning, and the run continues. With `--vcon-forward-once`, the run exits 1.

### `the answer is larger than {} bytes (--vcon-fetch-max-size); nothing was written`

The store's answer was larger than the `--vcon-fetch-max-size` limit (`{}` bytes), so sipnab wrote nothing.

**What to do:** If you expect a container that large, raise `--vcon-fetch-max-size`.

**Exit code:** 1.

### `the answer's status line and headers are larger than {max} bytes ({flag})`

The store's answer had a status line and headers larger than the limit. So sipnab stopped reading it.

- `{max}` is the limit in bytes (default 65536).
- `{flag}` is the setting that controls it:
  - `--vcon-forward-max-response-head` for the forwarder;
  - `--vcon-fetch-max-response-head` for the fetcher.
- The forwarder treats this as a failed send, and retries the container.
- The fetcher records that uuid as failed.

**What to do:** Raise the limit with the flag the message names, or with `[vcon_forward] max_response_head` or `[vcon_fetch] max_response_head` in the config file.

**Exit code:** For the forwarder, none, because the forwarder retries the container. With `--vcon-forward-once`, the run exits 1. For the fetcher, 1.

### `{url}: the container is not JSON: {e}`

The store's answer from `{url}` is not JSON. `{e}` is the parser's reason.

**What to do:** Check that `{url}` is the store's read URL.

**Exit code:** 1.

### `{url}: the container's uuid is {}, not the one asked for; nothing was written`

The container that the store returned carries a different `uuid` (`{}`, or `missing`) from the one requested. So sipnab did not write it.

**What to do:** Report it to the store's operator.

**Exit code:** 1.

### `the first retry delay, {} s from {}, is longer than the longest, {} s from {}; give a first delay no longer than the cap`

The vCon forwarder's first retry delay is longer than its longest retry delay.

- The four `{}` are, in order:
  - the first delay in seconds, and where it came from;
  - the longest delay, and where it came from.
- A source is one of:
  - `--vcon-forward-backoff-first` or `--vcon-forward-backoff-cap`;
  - `[vcon_forward] backoff_first` or `[vcon_forward] backoff_cap`;
  - `the default` (2 for the first delay, 300 for the longest).
- When sipnab finds this while it loads the configuration file, the printed line starts with `invalid config value: `.

**What to do:** Make the first delay no longer than the longest: lower `backoff_first` or `--vcon-forward-backoff-first`, or raise `backoff_cap` or `--vcon-forward-backoff-cap`.

**Exit code:**

- 1 when both values came from the configuration file or the defaults;
- 2 when a command-line flag supplied one of them.

### `The {what} for Call-ID '{}' would not serialize: {e}`

sipnab built the vCon for the named Call-ID but could not turn it into JSON. `{what}` is `vCon` for a normal container, or `withheld-dialog vCon` for a tombstone. `--content-deny-tombstone` writes a tombstone for a call that the `--content-deny-header` rule withheld. The text after the colon is the reason from the serializer.

**What to do:** Report the message and the Call-ID as a sipnab issue. No flag changes this.

**Exit code:** 1.

### `'{shown}': {client} speaks http:// and https:// only`

The URL does not start with `http://` or `https://`, the only two schemes sipnab can send to. The line starts with the setting the URL came from, for example `--vcon-forward-url` or `[vcon_fetch] url`. `{shown}` is the URL as written, with any `user:password@` part replaced by `[redacted]`. `{client}` names the part of sipnab that reads the URL: `the forwarder`, `the fetcher`, `the enricher`, or `sipnab` for a URL named inside a vCon.

**What to do:** Write the URL with `http://` or `https://` in front, for example `https://store.example.com/v1/vcons`.

**Exit code:**

- 2 when the URL came from a flag (`--vcon-forward-url`, `--vcon-forward-replace-url`, `--vcon-forward-scitt-url` or `--vcon-fetch-url`);
- 1 when it came from the config file (`[vcon_forward] url`, `[vcon_forward] replace_url`, `[vcon_forward] scitt_url`, `[vcon_fetch] url` or `[[vcon.enrich]] url`).

### `'{url}': the {} kind reads at a URL template; write {{uuid}} where the uuid goes`

The fetcher's store kind is `generic` (the default, which `--vcon-fetch-kind` or `[vcon_fetch] kind` sets). That kind has no built-in read path, and the URL holds no `{uuid}`. `{url}` is the URL as parsed, and `{}` is the kind name. The line starts with `--vcon-fetch-url` or `[vcon_fetch] url`.

**What to do:** Do one of these:

- Write `{uuid}` in the URL where the container's uuid goes, for example `https://host/vcons/{uuid}`.
- Set `--vcon-fetch-kind` to `vcon-store`, `conserver` or `vcon-mcp`. These supply the read path.

**Exit code:** 2 when the URL came from `--vcon-fetch-url`, and 1 when it came from `[vcon_fetch] url`.

### `'{}': the read URL holds no {{uuid}}`

The fetcher's read URL holds no `{uuid}` when the fetcher starts. `{}` is the URL.

- The settings step (`read_url`) always produces a URL holding `{uuid}`. Or it refuses the run with its own message first.
- So a command-line run does not reach this check.

**What to do:** Write `{uuid}` in `--vcon-fetch-url` (or `[vcon_fetch] url`) where the uuid goes, or use a `--vcon-fetch-kind` that supplies the read path.

**Exit code:** 2.

### `{uuid}: the store holds no such vCon (404)`

The store answered 404: it holds no vCon with that `uuid`.

**What to do:** Check the `uuid`.

**Exit code:** 1.

### `` {} {} the 'vcon' Cargo feature, which this build does not carry. Rebuild with --features vcon (or --features full); `sipnab --version` lists the features a binary was built with ``

This sipnab binary does not include the `vcon` Cargo feature (a build-time option). That feature contains the vCon exporter. vCon is a JSON format for a recorded conversation.

- The first `{}` lists the vCon flags you gave. They come from `--export-vcon`, `--export-vcon-when`, `--export-vcon-dir`, `--vcon-digest` and `--vcon-max-inline-media`.
- The second `{}` is `needs` or `need`.

**What to do:** Use a sipnab binary built with `--features vcon` or `--features full`, or remove the listed flags. `sipnab --version` lists the Cargo features that a binary includes.

**Exit code:** 2.

### `The vCon for Call-ID '{call_id}' would not serialize: {e}`

sipnab built the vCon container for `{call_id}` but could not convert it to JSON. `{e}` is the JSON serializer's error. sipnab writes nothing for that call.

**What to do:** The code offers no flag that avoids this condition. Report it with the command line you used.

**Exit code:** 1.

### `{flag} '{}': not a directory`

The path given to `{flag}` exists and is not a directory. `{flag}` is `--vcon-fetch-out`, where the fetcher writes the containers it fetches, or `--vcon-audio-fetch-out`, where `--vcon-audio-fetch` writes the audio. `{}` is the path.

**What to do:** Name a directory, or a path that does not exist yet. sipnab creates a missing directory with mode 0700.

**Exit code:** 2.

### `--vcon-fetch requires the 'vcon' feature (not compiled in)`

`--vcon-fetch` downloads stored vCons (a JSON container format for conversation records) by UUID. This build does not include the `vcon` feature, so it has no fetcher.

**What to do:** Use a sipnab build that includes the `vcon` feature.

**Exit code:** 2.

### `vCon forwarder stopped: {why}`

The store answered 401 or 403, which refuses the credential or the client for every container alike, so the forwarder stopped. It sends nothing more, and every container stays in the spool. `{why}` holds the request, the status, the container name and the start of the store's answer (at most 200 bytes, credential removed).

**What to do:** Check the credential (`--vcon-forward-auth-file`, `[vcon_forward] auth_file` or `SIPNAB_VCON_FORWARD_AUTH`) and the header name it uses. If a Cloudflare front answered 403 with `error code: 1010`, check that nothing in front of sipnab replaces its `User-Agent` header.

**Exit code:** 3.

### `--vcon-forward '{}' is not a directory`

The spool path given to `--vcon-forward` exists and is not a directory. The spool is the `--export-vcon-dir` directory that the forwarder sends containers from. `{}` is the path.

**What to do:** Pass the directory that `--export-vcon-dir` writes to.

**Exit code:** 2.

### `--vcon-forward needs a credential: give {AUTH_FLAG}, {AUTH_KEY} in the config file, or the SIPNAB_VCON_FORWARD_AUTH environment variable`

You gave `--vcon-forward` with no credential for the store from any source. The forwarder sends one authentication header with every request and does not run without it.

**What to do:** Give `--vcon-forward-auth-file FILE`, set `[vcon_forward] auth_file` in the config file, or set the `SIPNAB_VCON_FORWARD_AUTH` environment variable. The file holds one line, `Header-Name: value`, or the bare key with a `--vcon-forward-kind` other than `generic`. Other users must not be able to read it (`chmod 600`).

**Exit code:** 2.

### `{from} needs --vcon-forward-scitt-url ([vcon_forward] scitt_url): the transparency service the lifecycle statements go to`

You gave a SCITT setting, such as `--vcon-forward-scitt-issuer` or `[vcon_forward] scitt_sign_key`, without the URL of the transparency service. `{from}` names the setting. The other SCITT settings do nothing without the URL.

**What to do:** Give `--vcon-forward-scitt-url URL` or `[vcon_forward] scitt_url`, or remove the SCITT settings.

**Exit code:** 2.

### `{issuer_from} {issuer:?} is not a URI: give a scheme and more, such as https://pbx.example.com/sipnab, of 1 to {} characters`

The issuer of the lifecycle statements is not a URI. `{issuer_from}` names `--vcon-forward-scitt-issuer` or `[vcon_forward] scitt_issuer`, `{issuer:?}` is the value, and `{}` is `MAX_ISSUER_LEN` (8192). A statement carries an X.509 chain, and [section 6 of draft-ietf-scitt-architecture-22](https://datatracker.ietf.org/doc/html/draft-ietf-scitt-architecture-22#section-6) then requires `iss` to be a URI of 1 to 8192 characters.

**What to do:** Give a URI with a scheme, such as `https://pbx.example.com/sipnab` or `urn:example:pbx-1`, with no spaces.

**Exit code:** 2.

### `{name}: a lifecycle statement did not register with {}; {record_name} says why`

The forwarder delivered the container `{name}`, and the transparency service at `{}` did not register one of its lifecycle statements: it refused it, or it did not answer. `{record_name}` is the `<name>.scitt` record beside the delivered container, which holds the status and the service's reason. The delivery stands, and sipnab does not retry the statement.

**What to do:** Read the record. A `400` names the service's reason, such as an algorithm its registration policy does not admit. Register the statement again by other means if the record must be complete.

**Exit code:** None. This is a warning, and the forwarder continues.

### `--vcon-forward requires the 'vcon' feature (not compiled in)`

`--vcon-forward` delivers a spool directory of vCon files to a store. This build does not include the `vcon` feature, so it has no forwarder.

**What to do:** Use a sipnab build that includes the `vcon` feature.

**Exit code:** 2.

### `--vcon-resign requires the 'vcon' feature (not compiled in)`

`--vcon-resign` re-signs a signed vCon for a long-term archive. This build does not include the `vcon` feature, so it cannot sign.

**What to do:** Use a sipnab build that includes the `vcon` feature.

**Exit code:** 2.

### `--vcon-resign: {message}`

`--vcon-resign` wrote nothing. `{message}` is the reason. It is one of these:

- `--vcon-resign-key: {e}`, when the new signer's key or certificate does not read, the key is not RSA or EC P-256, other users can read the key, or the certificate is not the key's. A certificate file that does not exist reads `--vcon-resign: --vcon-resign-key: cannot read 'nocert.pem': No such file or directory (os error 2)`. Exit code 2.
- a `[vcon_input]` or `--vcon-signer-ca` CA file that does not read. Exit code 2.
- `'{file}': {e}`, when sipnab refuses the input: it is not JSON, it is not the signed form, a signature does not verify, the signer checks refuse its outermost signer, or that signer's certificate is not valid now. An unsigned input reads ``--vcon-resign: 'notsigned.json': the vCon is not signed: draft-ietf-vcon-vcon-core-04 section 5.2.3 re-signs a signed vCon (the signed form, `payload` and `signatures`)``. Exit code 1.
- `cannot read '{file}': {e}`, or the input is over the 64 MiB limit for one container. An input that does not exist reads `--vcon-resign: cannot read 'in.json': No such file or directory (os error 2)`. Exit code 1.
- `'OUT' exists; sipnab never replaces it: name a new file`, or sipnab cannot create or write the output. Exit code 1.

**What to do:** Act on the reason. An input whose signing certificate has expired cannot be re-signed: [section 5.2.3 of draft-ietf-vcon-vcon-core-04](https://datatracker.ietf.org/doc/html/draft-ietf-vcon-vcon-core-04#section-5.2.3) re-signs before it expires.

**Exit code:** 1 or 2, as listed.

### `'{}' is {len} bytes, over the {cap}-byte limit for one container`

`--vcon-resign` names an input over the 64 MiB limit for one vCon container, the limit `-I` applies too. sipnab reads nothing of it. The message follows `--vcon-resign: `.

**What to do:** Check the file is the signed vCon you meant.

**Exit code:** 1.

### `--vcon-audio-fetch requires the 'vcon' feature (not compiled in)`

`--vcon-audio-fetch` reads back the audio a vCon names by `url`. This build does not include the `vcon` feature, so it cannot read a vCon.

**What to do:** Use a sipnab build that includes the `vcon` feature.

**Exit code:** 2.

### `--vcon-audio-fetch: {reason}`

`--vcon-audio-fetch` did not write a recording, or any. `{reason}` is why. sipnab prints one line for each recording it refused, and writes the others. It is one of these:

- `--vcon-key: {e}`, or the setting that names another `[vcon_input]` or `--vcon-signer-ca` file that does not read, followed by the reason; or `--vcon-audio-fetch-ca: {e}` or `--vcon-audio-fetch-extra-ca: {e}` for a CA file that does not load. A CA file that does not exist reads `--vcon-audio-fetch: --vcon-audio-fetch-ca: noca.pem: No such file or directory (os error 2)`. Exit code 2.
- `--vcon-audio-fetch-out '{dir}': {e}`, an output directory sipnab cannot create, or `--vcon-audio-fetch-out '{dir}': not a directory`. A path under a regular file reads `--vcon-audio-fetch: --vcon-audio-fetch-out 'afile/sub': Not a directory (os error 20)`. Exit code 2.
- `'{file}': {e}`, when the container does not open: it is not a vCon, a signature does not verify, the key does not decrypt it, or the signer checks refuse its signer. A text file reads `--vcon-audio-fetch: 'notes.txt': not a vCon container: not JSON (expected value at line 1 column 1)`. Exit code 1.
- `'FILE': the vCon has no uuid to name a file by`, or `'FILE': no recording in the vCon names a url`. Exit code 1.
- `dialog {index}: {reason}`, naming the recording's index in `dialog`, when sipnab refused that recording. The entries below list the reasons. A recording whose `mediatype` is `text/plain` reads `--vcon-audio-fetch: dialog 0: mediatype "text/plain" is not audio sipnab writes (audio/x-wav, audio/ogg)`. Exit code 1.
  - `names no mediatype, so sipnab cannot tell what audio it is`, or `mediatype {mediatype:?} is not audio sipnab writes (audio/x-wav, audio/ogg)`.
  - `names no content_hash, so the file cannot be checked`, or `content_hash does not match the file: the file is not the one the vCon names`. sipnab checks the hash before it decrypts the file or writes anything.
  - `the file is a JWE and did not decrypt: {e}`, with the decryption error as `{e}`: the file names no recipient that the key that opened the container decrypts.
  - a connection, TLS or HTTP refusal from the server that holds the file.

**What to do:** Act on the reason. A file whose hash does not match is not the one the vCon names: fetch it again from where your storage keeps it, and do not use it.

**Exit code:** 1 or 2, as listed.

### `'{}' exists; sipnab never replaces it: name a new directory`

`--vcon-audio-fetch` found a file at the path it writes a recording to, `<uuid>-dialog<N>.wav` or `.ogg` in `--vcon-audio-fetch-out`. `{}` is the path. sipnab fetches nothing for that recording and keeps the file. The message follows `--vcon-audio-fetch: dialog N: `.

**What to do:** Name a new `--vcon-audio-fetch-out` directory, or move the file away.

**Exit code:** 1.

### `has content_hash {expected:?}, and sipnab checks sha512 only`

The recording's `content_hash` names a hash algorithm other than SHA-512. sipnab checks every file it fetches before it reads it, and checks SHA-512 only, the algorithm draft-ietf-vcon-vcon-core-04 section 2.2 names. sipnab writes nothing for the recording. The message follows `--vcon-audio-fetch: dialog N: URL: `.

**What to do:** Check the file with a tool that supports the algorithm the vCon names.

**Exit code:** 1.

### `the audio is not {} (it does not start with {:?})`

The file the recording names matched its `content_hash`, and, decrypted when it was a JWE, it is not a WAV file (`RIFF`) or an Ogg file (`OggS`) as its `mediatype` says. sipnab writes nothing for the recording. The message follows `--vcon-audio-fetch: dialog N: URL: `.

**What to do:** Check what the vCon's producer wrote at that URL.

**Exit code:** 1.

### `the file is a JWE whose cty is {cty:?}, not the mediatype {mediatype:?}`

The file the recording names is a JWE, and the media type in its `cty` header is not the recording's `mediatype`. sipnab does not decrypt it. The message follows `--vcon-audio-fetch: dialog N: URL: `.

**What to do:** Check what the vCon's producer wrote at that URL.

**Exit code:** 1.

### `url {url:?} ends in no file name sipnab reads beside the container`

With `--vcon-audio-fetch-local`, sipnab reads the file named by the last segment of the recording's `url` from the directory that holds the vCon. That segment is empty, starts with a dot, or holds a character other than ASCII letters, digits, `-`, `_` and `.`, so it could name a file elsewhere. sipnab reads nothing for the recording.

**What to do:** Fetch the file from the URL, without `--vcon-audio-fetch-local`.

**Exit code:** 1.

### `url {url:?} is not https://, and draft-ietf-vcon-vcon-core-04 section 2.4.1 says "HTTPS MUST be used for retrieval"; nothing was fetched`

The recording's `url` is not an `https://` URL. sipnab does not connect. A `[[vcon.rule]]` with `audio = "url"` refuses an `audio_url_base` that is not `https://`, so sipnab writes no such URL itself.

**What to do:** If the file is beside the container, read it with `--vcon-audio-fetch-local`. Otherwise fetch it from the URL some other way, and check its SHA-512 against the `content_hash`.

**Exit code:** 1.

### `{url} answered {}`

The server that holds a recording's file answered `GET` with a status other than `2xx`. `{}` is the status. sipnab writes nothing for the recording. The message follows `--vcon-audio-fetch: dialog N: `.

**What to do:** Check the file is at that URL, and that the server serves it without a credential.

**Exit code:** 1.

### `{url}: the answer is larger than {} bytes ({max_size_setting})`

The file a recording names is larger than the limit. `{}` is the limit and `{max_size_setting}` the flag that sets it, `--vcon-audio-fetch-max-size`. sipnab writes nothing for the recording.

**What to do:** Raise `--vcon-audio-fetch-max-size`, if the file is the size you expect for the call.

**Exit code:** 1.

### `{url}: {problem}, so the file is not whole`

The server that holds a recording's file closed the connection before it sent the length it declared. `{problem}` gives the two lengths. sipnab writes nothing for the recording.

**What to do:** Run the command again. If it recurs, check the server.

**Exit code:** 1.

### `--vcon-validate requires the 'vcon' feature (not compiled in)`

`--vcon-validate` checks a container against the vCon schema sipnab ships, and the schema is part of the `vcon` feature. This binary does not include it.

**What to do:** Use a build with the `vcon` feature: the release binaries and `cargo install sipnab --features full` include it.

**Exit code:** 2.

### `--vcon-validate {}: {why}`

`--vcon-validate <FILE>` could not check the file. The first `{}` is the path, and `{why}` is one of these:

- sipnab could not read the file: the operating system's reason, such as `No such file or directory (os error 2)`.
- `the body must be a JSON vCon container`: the file is not JSON.
- `a vCon container is a JSON object; pass the container itself, not a string or array holding it`: the file is JSON but not an object.
- `sipnab must not validate this vCon container: {why}`: the container lists a `critical` extension sipnab does not support, which draft-ietf-vcon-vcon-core-04 section 4.1.4 forbids operating on.
- A signed, encrypted or gzip container that does not open, with the reason.

An invalid container is not this message: it prints its findings and exits 3.

**What to do:** Check the path and that the file is the container itself. For a `critical` extension, this sipnab cannot check the container.

**Exit code:** 1.

### `--vcon-spool-status requires the 'vcon' feature (not compiled in)`

`--vcon-spool-status` counts the vCon export spool: the containers pending, delivered and failed. This build does not include the `vcon` feature, so it cannot read the spool.

**What to do:** Use a sipnab build that includes the `vcon` feature.

**Exit code:** 2.

### `--vcon-spool-status: {e}`

`--vcon-spool-status` could not report on the spool. `{e}` is the reason. It is one of these:

- `cannot read '{path}': {e}`, when the spool directory, or its `delivered/` or `failed/` directory, exists but sipnab cannot list it;
- the reason sipnab could not write the report as JSON.

A directory that does not exist is not an error: it counts as empty.

**What to do:** Check the path. Check that the user sipnab runs as can list the spool directory, and the `delivered/` and `failed/` directories beside it.

**Exit code:** 1.

### `cannot read '{path}': {e}`

The spool status could not list a directory. `{path}` is the spool directory, or its `delivered/` or `failed/` directory, and `{e}` is the operating system's reason. The command line prints it after `--vcon-spool-status: `.

**What to do:** Check that the user sipnab runs as can list that directory.

**Exit code:** 1.

### `{shown} is missing beside the container`

The spool status found a container in `failed/` with no failure record beside it. `{shown}` is the record's file name, the container's name followed by `.error.json`. This is not an error message: it is the `record_problem` value for that container in the status report, and the report continues.

**What to do:** Read the container itself to find out why the forwarder moved it to `failed/`. Or run the forwarder again on it.

**Exit code:** None. It is a field in the report.

### `{shown} cannot be read: {e}`

The spool status found a failure record beside a container in `failed/` and could not read it. `{shown}` is the record's file name, and `{e}` is the operating system's reason. It is the `record_problem` value for that container in the status report, and the report continues.

**What to do:** Check that the user sipnab runs as can read the record.

**Exit code:** None. It is a field in the report.

### `{shown} is {size} bytes, past the {MAX_RECORD_READ}-byte bound this reads; read the file on the host`

The spool status found a failure record larger than it reads. `{shown}` is the record's file name, `{size}` its size, and `{MAX_RECORD_READ}` the bound, 1048576 bytes. It is the `record_problem` value for that container in the status report, and the report continues.

**What to do:** Read the record on the host with a text viewer.

**Exit code:** None. It is a field in the report.

### `writing --redact-map '{}': {e}`

sipnab created the `--redact-map` file, but a write to it failed part way. The text after the path is the operating system's reason.

**What to do:** Check free space on that filesystem, delete the partial map file, and run the export again.

**Exit code:** 1.

### `{uuid}: written to {}, but the schema refuses it ({} finding(s)): {}`

sipnab wrote the vCon `{uuid}` to the named file, but the file fails the vCon schema check. The number of findings and each finding follow. sipnab logs this as a warning, but a container with findings makes the run exit 1.

**What to do:** Read the findings. The file holds what the store returned.

**Exit code:** 1.

### `{url}: {e}`

The request to `{url}` failed before an answer arrived. `{e}` is the reason (for example a connection or TLS error).

**What to do:** Check the URL, the network path, and the store's certificate.

**Exit code:** 1.

### `{uuid}: {why}`

sipnab did not write the vCon `{uuid}`. `{why}` is the reason, one of the `--vcon-fetch` messages in this section.

**What to do:** Follow the reason that the message gives.

**Exit code:** 1, or 3 when the store refused the credential.

### `{}: {e}`

sipnab could not write the fetched vCon to the file named before the colon. `{e}` is the operating system's reason.

**What to do:** Check space and permissions in the `--vcon-fetch-out` directory.

**Exit code:** 1.

### `Calls were still waiting for [[vcon.enrich]] after an hour; their containers are not written.`

A live capture ended on its own (`--duration`) while calls still waited for an [`[[vcon.enrich]]`](vcon.md#enrich-a-call-before-it-is-written) service. An hour passed without them finishing.

- Its `timeout_secs` bounds each service call.
- So this means a service kept every call waiting its full timeout.

**What to do:**

- Check the service that each earlier `{label}[[vcon.enrich]] '{}' for Call-ID '{call_id}': {}: {}. The container is written without its analysis and records this.` line names in its first `{}`.
- Lower its `timeout_secs`.
- Re-export the calls from a saved capture with `-I`.

**Exit code:** None. This is a warning, and the run ends.

### `{label}[[vcon.enrich]] '{}' for Call-ID '{call_id}': {}: {}. The container is written without its analysis and records this.`

An [`[[vcon.enrich]]`](vcon.md#enrich-a-call-before-it-is-written) service did not succeed for one call.

- `{label}` names the rule.
- The first `{}` is the service.
- `{call_id}` is the call.
- Then come the outcome (`failed`, `timeout`, `malformed` or `queue-full`) and what happened.
- sipnab writes the call's container without that service's analysis.
- Its `sipnab-enrichment` attachment records the same outcome.

**What to do:** Read the detail: `failed` is the service's HTTP status or exit status, `timeout` its `timeout_secs`, `malformed` an answer that is not an `analysis` list. `queue-full` means 64 calls were waiting. The service is slower than the calls arrive.

**Exit code:** None. This is a warning, and the run continues.

### `{label}Could not write '{}' after enrichment: {e}`

On a live capture, sipnab enriched a call's container and then could not write it to its spool. `{label}` names the rule, `{}` the path and `{e}` the operating-system error.

**What to do:** Check the spool directory's free space and permissions.

**Exit code:** None. This is a warning, and the run continues.

### `answered HTTP {status}: {excerpt}`

The `detail` an [`[[vcon.enrich]]`](vcon.md#enrich-a-call-before-it-is-written) records when its URL answered with a status other than 2xx. `{status}` is the status and `{excerpt}` the start of the answer. It appears as the last `{}` of the `{label}[[vcon.enrich]] '{}' for Call-ID '{call_id}': {}: {}. The container is written without its analysis and records this.` line, and in the container's `sipnab-enrichment` attachment.

**What to do:** Fix the service. The excerpt is its own reason.

**Exit code:** None. sipnab writes the call without the service's analysis.

### `answered with more than {MAX_ANSWER_BYTES} bytes`

The `detail` an [`[[vcon.enrich]]`](vcon.md#enrich-a-call-before-it-is-written) records when the service's answer was larger than 16 MiB, which sipnab does not read.

**What to do:** Make the service answer with less: an analysis, not the audio.

**Exit code:** None. sipnab writes the call without the service's analysis.

### `analysis {i} has encoding '{encoding}'; core-04 allows none, json and base64url`

The `detail` of a `malformed` outcome: entry `{i}` of an [`[[vcon.enrich]]`](vcon.md#enrich-a-call-before-it-is-written) service's `analysis` has an `encoding` core-04 does not define. `{encoding}` is the value. sipnab keeps none of that answer.

**What to do:** Answer with `encoding` `none`, `json` or `base64url`.

**Exit code:** None. sipnab writes the call without the service's analysis.

### `is a {WTF_TYPE} with encoding '{encoding}'; the WTF draft requires json`

Part of the `detail` of a `malformed` outcome, after `analysis {i}`: a `[[vcon.enrich]]` service answered with a `wtf_transcription` whose `encoding` is not `json`. `{WTF_TYPE}` is `wtf_transcription` and `{encoding}` the value sent. [Section 6.1 of draft-howe-vcon-wtf-extension-02](https://datatracker.ietf.org/doc/html/draft-howe-vcon-wtf-extension-02#section-6.1) requires `json`. sipnab keeps none of that answer.

**What to do:** Send the transcription as a JSON object with `encoding` `json`.

**Exit code:** None. sipnab writes the call without the service's analysis.

### `is a {WTF_TYPE} whose {what}`

Part of the `detail` of a `malformed` outcome, after `analysis {i}`: a `wtf_transcription` from a `[[vcon.enrich]]` service lacks a member the WTF draft requires, or holds one out of range. `{what}` names it, such as `segments[0] ends at 1, not after its start 2` or `metadata has no model string`. sipnab keeps none of that answer.

**What to do:** Fix the service's transcription to carry the `transcript`, `segments` and `metadata` members the WTF transcription check in the vCon guide lists.

**Exit code:** None. sipnab writes the call without the service's analysis.

### `a provenance whose model has no {key}`

Part of the `detail` of a `malformed` outcome, after `analysis {i} has`: an analysis entry from a `[[vcon.enrich]]` service carries its own `provenance` record, and the record's `model` has no `vendor` or no `name`. `{key}` is the missing member. [Section 4.2.1 of draft-howe-vcon-provenance-00](https://datatracker.ietf.org/doc/html/draft-howe-vcon-provenance-00#section-4.2.1) requires both. sipnab keeps none of that answer.

**What to do:** Send `model.vendor` and `model.name`, or leave `provenance` out and let sipnab write it from the entry's `vendor` and `product`.

**Exit code:** None. sipnab writes the call without the service's analysis.

### `the answer has attachments, and sipnab carries an enrichment's attachment only for a [[vcon.enrich]] with lawful_basis = true, and only a {LAWFUL_BASIS} one`

The `detail` of a `malformed` outcome: a `[[vcon.enrich]]` service answered with an `attachments` list, and its entry does not set `lawful_basis = true`. `{LAWFUL_BASIS}` is `lawful_basis`. sipnab writes no lawful basis of its own and carries one from a service only when you allow it. sipnab keeps none of that answer.

**What to do:** Set `lawful_basis = true` on the `[[vcon.enrich]]` entry if that service is the source of the lawful basis you want carried, or remove `attachments` from its answer.

**Exit code:** None. sipnab writes the call without the service's analysis.

### `has a {other} member, which sipnab cannot carry as sent`

Part of the `detail` of a `malformed` outcome, after `attachment {i}`: a lawful basis attachment from a `[[vcon.enrich]]` service has a member other than `purpose`, `start`, `party`, `dialog`, `encoding`, `body` and `mediatype`. `{other}` is the member. sipnab carries the attachment unchanged or not at all. sipnab keeps none of that answer.

**What to do:** Send the attachment with those members only.

**Exit code:** None. sipnab writes the call without the service's analysis.

### `has a purpose other than {LAWFUL_BASIS}`

Part of the `detail` of a `malformed` outcome, after `attachment {i}`: an attachment from a `[[vcon.enrich]]` service with `lawful_basis = true` has a `purpose` other than `lawful_basis`. `{LAWFUL_BASIS}` is `lawful_basis`. sipnab carries no other kind of attachment from a service. sipnab keeps none of that answer.

**What to do:** Answer with lawful basis attachments only, `purpose` `lawful_basis`.

**Exit code:** None. sipnab writes the call without the service's analysis.

### `has a body whose {what}`

Part of the `detail` of a `malformed` outcome, after `attachment {i}`: the body of a lawful basis attachment from a `[[vcon.enrich]]` service lacks a member [section 5.2 of draft-howe-vcon-lawful-basis-02](https://datatracker.ietf.org/doc/html/draft-howe-vcon-lawful-basis-02#section-5.2) requires, or holds one of the wrong type. `{what}` names it, such as `purpose_grants[0] has no boolean granted`. sipnab keeps none of that answer.

**What to do:** Fix the body the service sends to the shape of section 5.2.

**Exit code:** None. sipnab writes the call without the service's analysis.

## G.729 tables (`sipnab g729`)

`sipnab g729 install` and `sipnab g729 status` print these messages.
[G.729 decoding](g729.md) describes the command. Each one stops the command
with exit code 1 and installs nothing. A table file already in place stays as
it was.

### `No place to install {TABLE_FILE_NAME}: give --g729-tables PATH, set [g729] tables, or set HOME`

`sipnab g729 install` has nowhere to write the table file. The command line
has no `--g729-tables`, the config file has no `[g729] tables`, and
neither `HOME` nor `XDG_CONFIG_HOME` names a directory, which is usual for a
service account. `{TABLE_FILE_NAME}` is `g729-tables.bin`.

**What to do:** Give the path: `sipnab g729 install --g729-tables /srv/sipnab/g729-tables.bin`,
and give the same path to the capture runs, or set `[g729] tables`.

**Exit code:** 1.

### `Refused {what}: its sha256 is {actual}, expected {PACKAGE_SHA256} (the ITU-T G.729 (06/2012) Release 3 package). Nothing was installed.`

The package is not the one sipnab pins. `{what}` is the zip `--from` named,
or "the download from" and the itu.int URL. `{actual}` is the sha256 of what
sipnab read, and `{PACKAGE_SHA256}` is the pinned one,
`979680ff3b52b13a5701453178efd32b53e340114638fd330fdb6669eec86620`. A
download that stopped part way, a proxy's error page, or another release of
the package each give another hash.

**What to do:** Download the package again from the URL `sipnab g729 install`
prints, check that `sha256sum` prints the pinned hash, and run the command
again. To install from a copy, give `--from` the zip itself.

**Exit code:** 1.

### `Refused the table file {}: its values sha256 is {}, expected {}. Nothing was installed.`

`--from` named a table file whose layout is right but whose values differ
from the ones sipnab pins. The placeholders are the file, the sha256 of its
values, and the pinned one. Someone changed the file, or built it from a
different package.

**What to do:** Copy the table file again from a host where
`sipnab g729 status` reports the pinned values hash, or install from the ITU-T
package instead.

**Exit code:** 1.

### `Refused the table file {}: {other}. Nothing was installed.`

`--from` named a file that starts like a table file but is not one: the
wrong version, the wrong length, or an entry of the wrong size. `{other}` says
which.

**What to do:** Copy the file again. A copy cut short is the usual cause.

**Exit code:** 1.

### `Refused {}: {e}. Nothing was installed.`

The importer could not build the tables from the package. `{}` is the zip or
directory, and `{e}` is the reason: a pinned source file is not in it (the
directory does not hold the extracted package, or holds part of it), or the
imported values do not hash to the pinned value, and the message names both
hashes.

**What to do:** Give `--from` the whole package zip, or the directory
`python3 scripts/fetch-g729-vectors.py` fills (`crates/g729/test-vectors/itu-source`).

**Exit code:** 1.

### `Cannot read {}: {e}`

`--from` names a file sipnab cannot read. `{e}` is the operating system's
reason.

**What to do:** Check the path and its permissions.

**Exit code:** 1.

### `Cannot create {}: {e}`

sipnab cannot make the directory the table file goes in. `{e}` is the
operating system's reason.

**What to do:** Create the directory, or give `--g729-tables` a path in a
directory you can write.

**Exit code:** 1.

### `Cannot write the download in {}: {e}`

sipnab cannot write the downloaded package to a temporary file in the table
file's directory, where the importer reads it. `{e}` is the operating
system's reason, often a full disk.

**What to do:** Free about 19 MB in that directory, or choose another with
`--g729-tables`.

**Exit code:** 1.

### `Cannot write {}: {e}`

sipnab cannot write the table file. `{e}` is the operating system's reason.

**What to do:** Check the directory's permissions and free space.

**Exit code:** 1.

### `Cannot set the mode of {}: {e}`

sipnab wrote the table file but could not set its mode to 0644, so other
accounts, such as a service's, may not read it.

**What to do:** Set it yourself with `chmod 644`.

**Exit code:** 1.

### `Downloading {url} failed: {e}`

The download from itu.int did not complete. `{e}` is the reason: no route,
a refused certificate, or one of the two answers below.

**What to do:** Check that the host reaches `www.itu.int` over HTTPS. A host
that cannot: download the package elsewhere and run
`sipnab g729 install --from <the zip>`.

**Exit code:** 1.

### `itu.int answered {status}`

itu.int answered the download with an HTTP status other than 200. It is
part of the `Downloading {url} failed` message.

**What to do:** Try again later, or download the package with a browser and
install it with `--from`.

**Exit code:** 1.

### `itu.int answered more than {PACKAGE_BYTES} bytes, more than the package`

The answer is larger than the package (18,476,968 bytes), so it is not the
package. It is part of the `Downloading {url} failed` message.

**What to do:** Download the package with a browser, check its sha256, and
install it with `--from`.

**Exit code:** 1.

## Startup, privileges and the process

### `--allow-coredump: a core dump would contain the archive password this run holds`

A warning that sipnab prints in this case:

- this run holds an archive password; and
- the command line includes `--allow-coredump`.

The password comes from `--archive-password`, `--archive-password-file`, `--archive-password-command`, `--archive-password-stdin`, the `SIPNAB_ARCHIVE_PASSWORD` environment variable or a systemd credentials directory.

- sipnab normally disables core dumps while it holds a password.
- With `--allow-coredump` it leaves them enabled. So a crash could write the password to a core file.

**What to do:** Remove `--allow-coredump` to have sipnab disable core dumps while it holds the password. Keep it only if a core file containing the password is acceptable.

**Exit code:** None. This is a warning, and the run continues.

### `Capture thread exited before signaling ready`

sipnab started its capture thread. It waited for the thread to report that its source (interface, file or socket) was open. But the thread ended without reporting either success or failure.

**What to do:** Re-run with `SIPNAB_LOG=debug` to see what the capture thread logged before it ended. Report the output if the cause is not shown.

**Exit code:** 1.

### `Could not block privilege escalation through exec: {e}`

At startup sipnab sets the Linux `PR_SET_NO_NEW_PRIVS` flag. That flag stops any program it later starts from gaining privileges through a `setuid` or `setgid` file.

- The `prctl` call that sets the flag failed. Or the flag read back as not set afterwards.
- `{e}` holds that reason, including the operating-system error.
- sipnab logs this as a warning, and continues without that protection.

**What to do:** No setting changes this step, and the run continues either way. The text after the colon names the system-call error to investigate on the host (the kernel or container must allow `prctl(PR_SET_NO_NEW_PRIVS)`).

**Exit code:** None. This is a warning, and the run continues.

### `Could not start the scanner-kill worker process: {e}. The --kill-scanner defense is DISABLED for this run; detection, alerting and reporting continue.`

sipnab answers SIP scanners from a separate worker process (a copy of its own executable), and starting that process failed. `{e}` is the operating system error. The scanner-kill response (`--kill-scanner`, `[security] kill_scanner` or `-K`) is off for this run. Detection, alerting and reporting continue.

**What to do:**

- Check that sipnab can still find and execute its executable at the path it started from.
- Check that the system allows it to create processes.
- Then restart the run.

**Exit code:** None. sipnab logs the error, and the run continues.

### `Failed to chroot: {e}`

`--chroot` or `[privilege] chroot` asked sipnab to change its root directory after opening the capture. The change failed.

- `{e}` names the failing call (`chroot` or `chdir(/)`) and the reason. Or it says the path is not valid UTF-8, or contains a null byte.
- Changing the root directory requires root privileges.

**What to do:** Run sipnab as root when using `--chroot`, make sure the directory exists, or remove `--chroot` and `[privilege] chroot`.

**Exit code:** 1.

### `Failed to disable core dumps: {e}`

The run loads decryption keys (`--tls-key`, `--keylog`, `--keylog-fd`, `--srtp-keys` or `--dtls-keylog`).

- So sipnab tells the operating system to exclude the process from core dumps. This keeps keys out of core files.
- The operating system refused.
- `{e}` names the failing call, and says that `--allow-coredump` runs anyway.

**What to do:** Pass `--allow-coredump` if a core file containing key material is acceptable. Otherwise, run on a system that allows the call.

**Exit code:** 1.

### `Failed to drop privileges: {e}`

Running as root, sipnab switches to an unprivileged account after opening the capture, and the switch failed. The account is `--user`, else `[privilege] user`, else `nobody`. `{e}` gives the reason, for example an account that does not exist or a credential call that failed.

**What to do:** Name an existing account with `--user <USER>` or `[privilege] user`, or pass `--no-priv-drop` to keep the current account.

**Exit code:** 1.

### `Failed to spawn processing thread: {e}`

In the TUI, the operating system refused to create the thread that reads packets into the call and stream lists. `{e}` is the operating system error.

**What to do:** sipnab offers no setting for this step. Act on the operating system reason in `{e}` and run again.

**Exit code:** 1.

### `Failed to start capture: {e}`

sipnab could not create the capture thread. `{e}` is the error from starting it (for example "Failed to spawn live capture thread").

**What to do:** Check the system's process and thread limits and available memory, then run again.

**Exit code:** 1.

### `--kill-spoof raw requires a raw socket but it could not be opened: {e}. Grant CAP_NET_RAW (sipnab --setup-caps / run under sudo) or use --kill-spoof ephemeral.`

`--kill-spoof raw` requires a raw network socket. With it, responses sent to SIP scanners carry the scanned party's address and port as their source.

- Opening the socket failed.
- `{e}` is the operating system error. Typically it is a missing `CAP_NET_RAW` capability (the Linux permission to open raw sockets).

**What to do:** Run `sipnab --setup-caps` once, or run the command under sudo, to grant `CAP_NET_RAW`. Alternatively use `--kill-spoof ephemeral`, or `--kill-spoof auto`, which falls back to sipnab's own port when the socket is unavailable.

**Exit code:** 1.

### `Permission denied on '{}'. Grant capture capabilities once (Linux), then re-run without sudo:\n  sipnab --setup-caps\n  # or run this invocation under sudo:\n  sudo sipnab\n  # equivalent manual step:\n  sudo setcap cap_net_raw,cap_net_admin+ep $(which sipnab)`

sipnab lacks the permission to open the capture device. `{}` names the interfaces involved. The message lists three ways to grant the capture capabilities.

**What to do:** Run `sipnab --setup-caps` once and re-run without sudo, run the command under sudo, or run `sudo setcap cap_net_raw,cap_net_admin+ep $(which sipnab)`.

**Exit code:** 1.

### `Processing thread panicked: {}`

When the TUI closed, sipnab found that the packet-processing thread had ended with a panic (an internal failure).

- `{}` is the panic message. Or it is `<non-string panic payload>` when the panic carried no text.
- sipnab's panic hook ends the whole process at the panic, with exit code 101 or a core dump.
- So this line appears only in a build or test that runs without that hook.

**What to do:** This is an internal failure in sipnab, not a setting. Report it with the command line you used and the log output.

**Exit code:** None. sipnab logs this during shutdown, and the TUI's own result decides the exit status.

### `Scanner-kill: raw socket unavailable ({e}); falling back to ephemeral source port. Kill responses will come from sipnab's own port.`

A warning: the default `--kill-spoof auto` tried to open a raw socket, so that scanner responses could carry the scanned party's address. The operating system refused (`{e}`).

- sipnab sends the responses from an ordinary UDP socket instead.
- So they come from sipnab's own address and port.

**What to do:** To send spoofed responses, grant `CAP_NET_RAW` with `sipnab --setup-caps` or run under sudo. To use sipnab's own port without this warning, pass `--kill-spoof ephemeral`.

**Exit code:** None. This is a warning, and the run continues.

### `sipnab: the terminal UI could not start: {e}. It needs a terminal; add -N for a run without one.`

The terminal UI returned an error, so the run ends with exit 1. `{e}` is the error. sipnab prints this line to standard error after it restores the terminal, so it is visible even with logging off.

**What to do:** Run sipnab in an interactive terminal, or add `-N` to run without the TUI.

**Exit code:** 1.

### `TUI error: {e}`

The terminal UI returned an error. Setting up the terminal (raw mode, the alternate screen), drawing a frame, or reading a key or mouse event failed. `{e}` is that error. The line `sipnab: the terminal UI could not start: {e}. It needs a terminal; add -N for a run without one.` follows it on standard error, with the same `{e}`.

**What to do:** Run sipnab in an interactive terminal, or add `-N` for a run without the TUI.

**Exit code:** 1.

## Analysis warnings

### `--since/--until: no dialog's first message falls in {window}; this capture's dialogs begin between {} and {}`

The time window that `--since` and `--until` give holds none of the capture's dialogs. So every listing is empty.

- `{window}` is the window, written `[start, end)`. It shows `unbounded` for a side you did not give.
- The two `{}` are the first-message times of the earliest and the latest dialog in the capture.
- sipnab prints this line on stderr, so a JSON stream on stdout stays valid.

**What to do:** Move the window to cover the times the line names.

**Exit code:** None. This is a notice, and the run continues.

### `--since/--until: no dialog in {window}; the capture holds no dialog`

You gave `--since` or `--until`, and the capture holds no dialog at all, so every listing is empty. `{window}` is the window, written `[start, end)`, with `unbounded` for a side you did not give.

**What to do:** Check that the input holds SIP traffic.

**Exit code:** None. This is a notice, and the run continues.

### `capture quality: {}. THIS ANALYSIS IS INCOMPLETE — the counts above are what sipnab RECEIVED AND UNDERSTOOD, not what crossed the wire. See docs/tuning-capture.md.`

The capture lost or could not read part of the traffic. The `{}` part lists each kind of loss, with a semicolon between them. All totals in the output describe what sipnab received and understood, not everything that crossed the wire.

**What to do:** Follow the advice in each listed part. [Tuning capture](tuning-capture.md) describes the capture settings.

**Exit code:** None. This is a warning, and the run continues.

### `Fix the decode before reading anything into the zero above: convert the capture (editcap -T ether) or open an issue naming the number(s) reported.`

The remedy for frames sipnab could not decode.

**What to do:** Convert the capture (`editcap -T ether`) or open an issue naming the reported number.

**Exit code:** None. This is a warning, and the run continues.

### `{snapped} frame(s) arrived truncated by the capture's snaplen and {snapped_undecodable} of them were cut too short to decode at all, so nothing in those was analyzed (raise --snaplen)`

Part of the capture-quality summary.

- The snapshot length (`snaplen`) is the most bytes the capture keeps of each packet.
- It cut `{snapped}` frames short.
- `{snapped_undecodable}` of them were too short to decode at all. So sipnab analyzed nothing in those frames.

**What to do:** Raise `--snaplen`.

**Exit code:** None. This is a warning, and the run continues.

### `{snapped} frame(s) arrived truncated by the capture's snaplen (headers kept, payload cut short — raise --snaplen if you need RTP payload, audio export or a faithful -O re-emit)`

Part of the capture-quality summary. The capture's snapshot length (snaplen, the most bytes the capture stores per frame) cut `{snapped}` frames short. sipnab kept and analyzed the headers, and the payload is missing.

**What to do:** Raise `--snaplen` if you need RTP payload, audio export or a complete `-O` copy.

**Exit code:** None. This is a warning, and the run continues.

### `{intact_undecodable} frame(s) reached sipnab intact and could not be decoded at all, so nothing in them was analyzed (see the NOT DECODED line above for which link types, EtherTypes and IP protocols)`

Part of the capture-quality summary. `{intact_undecodable}` frames arrived complete, but no sipnab decoder could read them, so sipnab analyzed nothing in them. The `NOT DECODED` line names the link types, EtherTypes and IP protocols.

**What to do:** See the `NOT DECODED` line for the reasons. If the link type is the cause, convert the capture (for example `editcap -T ether`).

**Exit code:** None. This is a warning, and the run continues.

### `{holes} hole(s) in TCP streams, {hole_bytes} byte(s) of sequence space the capture never held, were skipped: reading resumed at the next SIP message behind each, and a message the hole cut is lost (packets the capture point missed)`

Part of the capture-quality summary. TCP streams had `{holes}` gaps, totaling `{hole_bytes}` bytes, that the capture never contained. sipnab skipped each gap and resumed reading at the next SIP message after it. A SIP message that a gap cuts through goes missing from the analysis.

**What to do:** Capture closer to the traffic, or with a larger buffer, so that the capture point does not miss packets.

**Exit code:** None. This is a warning, and the run continues.

### `IMPOSSIBLE RATE: {count} stream(s) carry more payload than their codec can produce — worst is {label} at {mult:.1}x its ceiling. The most common cause is the same traffic read twice: a directory holding a capture and its backup, or one call captured at two hops. Counts and rates in this run are inflated by that factor. sipnab does not de-duplicate, because two vantage points on one call are a legitimate input.`

At least one RTP stream carried more payload per second than its codec can produce. That means more than 15% over the codec's fixed rate, measured over at least 0.5 seconds.

- `{count}` is the number of streams.
- `{label}` names the worst one (codec, SSRC, source and destination).
- `{mult:.1}` is how many times over the ceiling that stream ran.
- sipnab does not check variable-rate codecs such as Opus.

**What to do:** Check the `-I` input for the same traffic read twice. For example, a directory holding a capture and its backup. Run again with one copy.

If you meant to supply two captures of one call from different points, the counts include both by design.

**Exit code:** None. This is a warning, and the run continues.

### `--kill-ua {pattern} names a User-Agent for the scanner detector, and nothing in this run builds that detector — so the pattern is read by nobody and the run would report no scanners whether or not one is there. Add --kill-scanner-detect-only (or set [security] kill_scanner_detect_only = true) to detect without answering, or --kill-scanner (or [security] kill_scanner = true), which on a live capture also answers the scanners it detects. sipnab will not turn either on for you.`

`--kill-ua` adds a User-Agent pattern for the scanner detector. This run does not build that detector, because you set none of `--kill-scanner`, `--kill-scanner-detect-only`, `[security] kill_scanner = true` or `[security] kill_scanner_detect_only = true`.

- `{pattern}` is the pattern you gave.
- sipnab does not turn scanner detection on by itself. On a live capture `--kill-scanner` also sends SIP responses to the detected scanners.

**What to do:** Add `--kill-scanner-detect-only` to detect scanners and send nothing. Add `--kill-scanner` instead to also answer them on a live capture. Or remove `--kill-ua`. Each flag has a configuration key in `[security]` with the same effect.

**Exit code:** 2.

### `{msgs} message(s) evicted from retained dialogs by idle compaction`

Part of the retention summary. Idle compaction removed `{msgs}` SIP messages from dialogs that sipnab kept.

**What to do:** Raise `--limit` or `--max-streams` to keep more.

**Exit code:** None. This is a warning, and the run continues.

### `{dropped} new dialog(s) refused at capacity (--no-rotate keeps the earliest)`

Part of the retention summary. sipnab refused `{dropped}` new dialogs because the dialog store was full, and `--no-rotate` keeps the earliest dialogs.

**What to do:** Raise `--limit`, or drop `--no-rotate` so that sipnab discards the oldest dialogs instead.

**Exit code:** None. This is a warning, and the run continues.

### `No SIP signaling found, but {rtp_packets} RTP packets across {streams} stream(s) were parsed.`

sipnab found no SIP, but it parsed `{rtp_packets}` RTP packets in `{streams}` streams, so the capture was readable.

**What to do:** If you expected signaling, check the capture point.

**Exit code:** None. This is a warning, and the run continues.

### `No SIP traffic found, but this capture is not empty: {} of {} STUN/TURN transaction(s) went unanswered — {} sent {} to {} {} time(s) and got nothing back.`

sipnab found no SIP, but STUN/TURN requests (the messages an endpoint uses to learn its public address) got no answer. The numbers are the unanswered transactions, the total transactions, and the first unanswered request's sender, method, destination and attempt count.

**What to do:** Read the next two lines.

**Exit code:** None. This is a warning, and the run continues.

### `No SIP traffic found. Check that the capture contains SIP packets (typically UDP port 5060-5061).`

The capture held no SIP that sipnab found, and nothing else explains it.

**What to do:** Check that the capture contains SIP (usually UDP port 5060-5061).

**Exit code:** None. This is a warning, and the run continues.

### `No SIP traffic was decoded — but {} of {frames_read} frame(s){share} could not be decoded at all, so this is not a finding that the capture contains no SIP. Undecodable: {}.`

sipnab decoded no SIP, and some frames failed to decode at all. So the zero is not a finding that the capture holds no SIP.

The numbers are the undecodable frames, the frames read, and the reasons.

**What to do:** Read the next line.

**Exit code:** None. This is a warning, and the run continues.

### `No SIP traffic was decoded, but TLS application data in this capture could not be decrypted (see above), so this is not a finding that the capture contains no SIP.`

sipnab decoded no SIP, and it could not decrypt TLS traffic in the capture, so SIP may be inside that traffic.

**What to do:** Follow the TLS decryption lines printed above.

**Exit code:** None. This is a warning, and the run continues.

### `NOT ANALYZED: {} further SIP message(s) were seen on ports outside --portrange and are in none of the totals above. Busiest: {}. Re-run with --portrange 1-65535 to include them.`

When sipnab reads a capture file, `--portrange` selects which ports carry SIP signaling.

- sipnab saw messages that look like SIP on other ports.
- It did not analyze them, and left them out of every total.
- The first `{}` is the count.
- The second lists up to five of the busiest ports, with message counts. A port here is the destination port of requests and the source port of responses.

**What to do:** Run again with `--portrange` widened to include the listed ports, or with `--portrange 1-65535` to include all of them.

**Exit code:** None. This is a warning, and the run continues.

### `NOT ANALYZED: {} SIP-over-WebSocket message(s) arrived on ports outside the WebSocket port set ({}) and are in none of the totals above. Busiest: {}. Re-run with --ws-portrange covering them (e.g. --ws-portrange 1-65535) to include them.`

sipnab unwrapped some messages as SIP carried in WebSocket frames. But they were on ports outside the WebSocket port set.

- So sipnab did not analyze them, and every total leaves them out.
- The first `{}` is the message count.
- The second is the current port set (default 80, 443, 8080, 8443, or the `--ws-portrange` range).
- The third lists up to five of the busiest ports, with message counts.

**What to do:** Run again with `--ws-portrange` covering those ports (for example `--ws-portrange 1-65535`), or set `[capture] ws_ports` in the configuration file.

**Exit code:** None. This is a warning, and the run continues.

### `NOT DECODED: {} of {frames_read} frame(s)`

Start of the NOT DECODED notice. The first number is how many frames sipnab could not decode, out of `{frames_read}` frames read. A percentage follows when `{frames_read}` is above zero.

**What to do:** Read the reasons on the same line.

**Exit code:** None. This is a warning, and the run continues.

### ` NOTHING IN THIS CAPTURE WAS READ — every frame failed to decode, so the totals above describe no traffic whatsoever and a zero among them is not evidence of absence.`

Every frame in the capture failed to decode.

- So every total sipnab printed describes no traffic.
- A zero is not evidence that something is absent.

**What to do:** Convert the capture to a link type sipnab reads (for example with `editcap -T ether`). Or open an issue naming the reported number.

**Exit code:** None. This is a warning, and the run continues.

### `{rotated} oldest dialog(s) discarded at capacity by rotation`

Part of the retention summary. sipnab discarded `{rotated}` of the oldest dialogs because the dialog store was full.

**What to do:** Raise `--limit` to keep more dialogs.

**Exit code:** None. This is a warning, and the run continues.

### `{if_dropped} packet(s) dropped by the interface or its driver (a bigger buffer cannot recover these — check the NIC and its offloads)`

Part of the capture-quality summary. The network interface or its driver dropped `{if_dropped}` packets before they reached the capture library.

**What to do:** A larger buffer does not recover these. Check the network card and its offload settings.

**Exit code:** None. This is a warning, and the run continues.

### `{dropped} packet(s) dropped by the kernel capture buffer (raise -B/--buffer, narrow the BPF filter, or lower --snaplen)`

Part of the capture-quality summary. The kernel capture buffer was full and lost `{dropped}` packets.

**What to do:** Raise `-B`/`--buffer`, narrow the BPF filter, or lower `--snaplen`.

**Exit code:** None. This is a warning, and the run continues.

### `{bad_ts} packet(s) had a corrupt capture timestamp and were stamped with the wall clock (timing analysis is unreliable for this run)`

Part of the capture-quality summary.

- `{bad_ts}` packets had a corrupt timestamp in the capture.
- sipnab gave them the current clock time instead.
- So timing figures for this run are not reliable.

**What to do:** Capture again, or repair the capture file. sipnab has no option that recovers the original timestamps.

**Exit code:** None. This is a warning, and the run continues.

### `; plus {} further frame(s) whose reason was not retained (the capture carried more distinct reasons than the tally holds)`

Continues the NOT DECODED notice. `{}` more frames failed to decode for a reason that the tally had no room to keep.

**What to do:** This part needs no action. The count is exact.

**Exit code:** None. This is a warning, and the run continues.

### ` produced nothing and are in none of the counts above. Reasons: {}`

Continues the NOT DECODED notice. Those frames are in none of the totals printed above. `{}` lists each reason with its number (link type, `EtherType` or IP protocol) and count.

**What to do:** Convert the capture (for example with `editcap -T ether`) or open an issue naming the reported number.

**Exit code:** None. This is a warning, and the run continues.

### `{flags} refused: security detection is built only by the headless single-capture path, and this run is {path}. Nothing would be detected and no finding reported, so an empty result would not be an all-clear — which is why this is refused rather than warned about. To detect, {remedy}.`

You gave security detection flags on a run that uses the parallel offline reader. That reader builds no detectors.

- sipnab picks that mode when `--cores` is above 1 with `-I`, and without multi-device capture.
- `{flags}` lists the detection settings that the run asked for. They come from `--kill-scanner`, `-K/--kill-target`, `--fraud-detect`, `--digest-leak`, `--reg-flood` and `--stir-shaken`, including ones turned on in the configuration file.
- `{path}` is `the --cores parallel offline reader`.
- `{remedy}` is `drop --cores (the single-core headless read detects)`.

**What to do:** Do one of these:

- Remove `--cores` (or set it to 1). The run then reads on a single core and builds the detectors.
- Remove the listed detection settings.

**Exit code:** 2.

### `retention: {}. The message and packet counts above are what sipnab READ, not what it kept — raise --limit, or --max-streams, to keep more.`

sipnab read more than it kept. The `{}` part lists what sipnab dropped (messages evicted, new dialogs refused, oldest dialogs discarded), separated by semicolons. The message and packet totals printed above count what sipnab read, not what it kept.

**What to do:** Raise `--limit`, or `--max-streams`, to keep more.

**Exit code:** None. This is a warning, and the run continues.

### `STIR/SHAKEN: unparseable Identity header: {e}`

`--stir-shaken` logs every Identity header in each SIP message. The Identity header is the STIR/SHAKEN caller-ID signature, a JWT called a PASSporT.

sipnab could not parse one Identity header, for one of these reasons. `{e}` says which.

- it does not have three parts separated by dots;
- its payload is not valid `base64url`;
- the payload is not the expected JSON.

**What to do:** No flag changes this. The message describes the SIP message as sipnab received it. Inspect the Identity header of that message in the capture.

**Exit code:** None. This is a warning, and the run continues.

### `That is a NAT-discovery failure, not a missing capture. An endpoint that cannot learn its reflexive address advertises its PRIVATE address in SDP, and the far end then sends media to somewhere it cannot reach — a call that signals cleanly and carries audio one way.`

Explains the unanswered STUN/TURN requests.

- An endpoint that cannot learn its public address advertises its private one in SDP. SDP is the media description in the call setup.
- That gives one-way audio.

**What to do:** Read the next line.

**Exit code:** None. This is a warning, and the run continues.

### `The requests drew no reply at all rather than a refusal, which points at something in the path discarding them rather than at the server. On school, campus and corporate networks that is most often a security appliance — web filter, secure web gateway, firewall or IPS — dropping UDP it does not recognize. Confirm whether one sits in this path and whether it permits UDP to the STUN/TURN port.`

The STUN/TURN requests drew no reply at all, which points at something in the path dropping UDP rather than at the server.

**What to do:**

- Check whether a web filter, secure web gateway, firewall or IPS sits in the path.
- Check whether it permits UDP to the STUN/TURN port.

**Exit code:** None. This is a warning, and the run continues.

### ` THIS ANALYSIS IS MOSTLY BLIND — the totals above describe the minority of the capture sipnab could read, so a zero among them is not evidence of absence.`

Half or more of the frames failed to decode.

- So the totals describe only the part of the capture sipnab could read.
- A zero is not evidence that something is absent.

**What to do:** Convert the capture (for example with `editcap -T ether`) or open an issue naming the reported number.

**Exit code:** None. This is a warning, and the run continues.

### `Tip: Use 'sipnab -N -I file.pcap --hexdump' to inspect raw packet content.`

sipnab prints this after the no-SIP line.

**What to do:** Run `sipnab -N -I file.pcap --hexdump` to inspect the raw packets.

**Exit code:** None. This is a warning, and the run continues.

### `{finding} Use --report to see stream details.`

sipnab adds this to the line above when you did not give `--report`. `{finding}` is that line.

**What to do:** Add `--report` to see the stream details.

**Exit code:** None. This is a warning, and the run continues.

## Library and parser errors

### `{what} contains invalid UTF-8`

Library parser error. Bytes that must be text are not valid UTF-8.

- `{what}` is `SIP first line` or `SDP body`.
- In the `sipnab` program, sipnab drops a SIP-looking packet that fails this way. It logs it only at debug level (`SIPNAB_LOG=debug`) as `SIP parse error: {what} contains invalid UTF-8`.
- `-x`/`--quiet-bad-parse` silences that line.
- sipnab does not use a SIP message body that fails this way for media setup. It prints no message for it.

**What to do:** The SIP first line or SDP body contained bytes that are not UTF-8 text.

**Exit code:** None. The error goes back to the program that calls the library.

### `empty {what}`

Library parser error: the parser received empty input.

- `{what}` names the expected input: `SIP message` (from `parse_sip` or `parse_sip_bytes`) or `SDP body` (from `parse_sdp`).
- In the `sipnab` program, sipnab drops a SIP-looking packet that fails this way. It logs it only at debug level (`SIPNAB_LOG=debug`) as `SIP parse error:` followed by this text.
- `-x`/`--quiet-bad-parse` silences that line.
- sipnab does not use a SIP message body that fails this way for media setup. It prints no message for it.

**What to do:** The input was zero bytes long. Library callers should pass the whole SIP message or SDP body.

**Exit code:** None. The error goes back to the program that calls the library.

### `{kind} encapsulation depth exceeds limit ({limit})`

Packet decoder error (library surface). A frame nests more encapsulation layers than the limit allows.

- Encapsulation layers are tunnels such as IP-in-IP, GRE, MPLS-in-IP, AH, ESP or UDP tunnels.
- `{kind}` is the layer that went over the limit.
- `{limit}` is the limit, 5.
- The limit protects the decoder from crafted frames.
- In the `sipnab` program, this text appears only in debug logging (`SIPNAB_LOG=debug`) as `Skipping unparseable packet: {kind} encapsulation depth exceeds limit ({limit})`.
- sipnab counts the frame in the headless (`-N`) end-of-run `NOT DECODED` summary, and in the `sipnab_capture_undecodable_frames_total` metric. The run continues.

**What to do:** No setting changes the limit. sipnab does not decode frames nested this deeply.

**Exit code:** None. This is a warning, and the run continues.

### `failed to decode {what}`

Packet decoder error from the library: sipnab could not decode a link or network layer of a captured frame.

- `{what}` names the layer, such as `Ethernet packet`, `IP from encapsulated Ethernet frame` or `WebSocket frame`.
- When the capture cut the frame short (`snaplen`), sipnab counts the frame as truncated rather than as a decode error.
- In the `sipnab` program this text appears only in debug logging (`SIPNAB_LOG=debug`). It is on a line that starts with `Skipping` and ends with this text.
- sipnab counts the frame in the headless (`-N`) end-of-run `NOT DECODED` summary, and in the `sipnab_capture_undecodable_frames_total` metric. The run continues.

**What to do:** If the summary reports the frames as truncated, capture again with a larger `--snaplen`. Otherwise the frame is in a format the decoder does not read.

**Exit code:** None. The error goes back to the program that calls the library, and a `sipnab` run skips the frame and continues.

### `gzip-compressed capture; decompress it first (sipnab's file loaders and decompress_capture do this automatically)`

Library error from `PcapReader::new`: the bytes passed to it are still gzip-compressed.

- `decompress_capture` and the file loaders in sipnab decompress before reading.
- So only a program that calls `PcapReader::new` directly on compressed bytes sees this.

**What to do:** Pass the bytes through `sipnab::capture::pcap_reader::decompress_capture` first, as the message says, and give the result to `PcapReader::new`.

**Exit code:** None. The error goes back to the program that calls the library.

### `gzip-compressed capture inflates past the {limit}-byte safety cap; raise --max-gunzip-bytes (or [limits] max_gunzip_bytes) for a capture you trust, or decompress it manually (e.g. gunzip) and open the raw file`

Decompressing a gzip-compressed capture would produce more than `{limit}` bytes. So decompression stopped.

- That limit is the in-memory safety cap (default 1 GiB, 1073741824 bytes).
- The `sipnab` command opens `-I` files through libpcap and its archive layer. Those report problems in their own words.
- This text comes from the library reader `PcapReader::new` or `decompress_capture`, and from the WebAssembly build's file loader.

**What to do:** Decompress the file with a separate tool such as `gunzip` and open the raw capture. A program that uses the library raises the cap with `sipnab::capture::pcap_reader::set_max_gunzip_bytes`.

**Exit code:** None. The error goes back to the program that calls the library.

### `gzip stream is corrupt or truncated: {source}`

Decompressing a gzip-compressed capture failed, because the compressed data has damage or ends early.

- `{source}` is the error from the decompression step.
- The `sipnab` command opens `-I` files through libpcap and its archive layer. Those report problems in their own words.
- This text comes from the library reader `PcapReader::new` or `decompress_capture`, and from the WebAssembly build's file loader.

**What to do:** Obtain a complete, undamaged copy of the `.gz` file.

**Exit code:** None. The error goes back to the program that calls the library.

### `{what} has no IP layer`

Packet decoder error (library surface). The frame carries no IP layer.

- Examples are ARP, a PPP frame without IP, a loopback frame of another address family, or an encapsulation that the decoder recognizes but cannot read.
- `{what}` names it.
- In the `sipnab` program, this text appears only in debug logging (`SIPNAB_LOG=debug`) as `Skipping unparseable packet: {what} has no IP layer`.
- sipnab counts the frame in the headless (`-N`) end-of-run `NOT DECODED` summary, and in the `sipnab_capture_undecodable_frames_total` metric. The run continues.

**What to do:** The run needs no action. Frames without IP carry no SIP or RTP.

**Exit code:** None. This is a warning, and the run continues.

### `ICMP packets are not processed by sipnab`

The packet decoder (`parse_packet`, part of the library) does not turn ICMP or ICMPv6 packets into SIP or RTP data. It returns this error for them.

- Before it returns, the native decoder records an ICMP error message that quotes an earlier packet. The record is evidence for the matching dialog.
- In the `sipnab` program this text appears only in debug logging (`SIPNAB_LOG=debug`). It is on a line that starts with `Skipping` and ends with this text.
- sipnab does not count the packet as undecodable.

**What to do:** You need to do nothing. Every ICMP packet ends this way after sipnab records any error evidence it carries.

**Exit code:** None. The error goes back to the program that calls the library, and a `sipnab` run skips the frame and continues.

### `invalid SIP first line '{line}': {reason}`

Library parser error: the first line ends in ` SIP/2.0`. So the parser reads it as a SIP request line. But it does not have the shape `METHOD Request-URI SIP/2.0`.

- `{line}` is the line.
- `{reason}` is the problem. It is `no space before SIP version` when no Request-URI sits between the method and the version.
- In the `sipnab` program, sipnab drops a SIP-looking packet that fails this way. It logs it only at debug level (`SIPNAB_LOG=debug`) as `SIP parse error:` followed by this text.
- `-x`/`--quiet-bad-parse` silences that line.

**What to do:** The request line has the wrong form. It must hold a method, a Request-URI and `SIP/2.0`, separated by spaces.

**Exit code:** None. The error goes back to the program that calls the library.

### `invalid SIP status code: '{code}'`

Library parser error: the first line starts with `SIP/2.0 `. So the parser reads it as a SIP response status line. But the word after it is not a whole number from 0 to 65535.

- `{code}` is that word.
- In the `sipnab` program, sipnab drops a SIP-looking packet that fails this way. It logs it only at debug level (`SIPNAB_LOG=debug`) as `SIP parse error:` followed by this text.
- `-x`/`--quiet-bad-parse` silences that line.

**What to do:** The status line has the wrong form. It must be `SIP/2.0`, a numeric status code and an optional reason phrase, such as `SIP/2.0 200 OK`.

**Exit code:** None. The error goes back to the program that calls the library.

### `Microsoft Network Monitor (.cap) format is not supported. Convert to pcap with: editcap -F pcap input.cap output.pcap`

The file starts with the Microsoft Network Monitor signature (magic `0x55424d47`). The built-in reader cannot read that capture format.

- The `sipnab` command opens `-I` files through libpcap and its archive layer. Those report problems in their own words.
- This text comes from the library reader `PcapReader::new` or `decompress_capture`, and from the WebAssembly build's file loader.

**What to do:** Convert the file to pcap with the `editcap -F pcap input.cap output.pcap` command that the message gives, then open the converted file.

**Exit code:** None. The error goes back to the program that calls the library.

### `no CRLF found — not a SIP message`

Library parser error: the data contains no CRLF, so it cannot be a SIP message. CRLF is carriage return and line feed, the line ending SIP requires.

- In the `sipnab` program, sipnab drops a SIP-looking packet that fails this way. It logs it only at debug level (`SIPNAB_LOG=debug`) as `SIP parse error:` followed by this text.
- `-x`/`--quiet-bad-parse` silences that line.

**What to do:** The input is not a SIP message, or it uses bare line feeds. SIP lines must end in CRLF.

**Exit code:** None. The error goes back to the program that calls the library.

### `no IP payload in {what}`

Packet decoder error from the library: the frame has an IP header, but no payload behind it to read.

- `{what}` names the packet (`packet` or `inner packet`).
- In the `sipnab` program this text appears only in debug logging (`SIPNAB_LOG=debug`). It is on a line that starts with `Skipping` and ends with this text.
- sipnab counts the frame in the headless (`-N`) end-of-run `NOT DECODED` summary, and in the `sipnab_capture_undecodable_frames_total` metric. The run continues.

**What to do:** The run needs nothing from you. The frame carries nothing that sipnab can analyze.

**Exit code:** None. The error goes back to the program that calls the library, and a `sipnab` run skips the frame and continues.

### `not a pcap/pcapng file (magic: 0x{magic:08x}). Supported formats: .pcap, .pcapng, .cap (pcap format), and their gzip-compressed variants (.pcap.gz, .pcapng.gz)`

The data does not start with a pcap, `pcapng` or Network Monitor signature. So it is not a capture file the built-in reader knows.

- `{magic}` is the first four bytes read as a little-endian number, in hex.
- The `sipnab` command opens `-I` files through libpcap and its archive layer. Those report problems in their own words.
- This text comes from the library reader `PcapReader::new` or `decompress_capture`, and from the WebAssembly build's file loader.

**What to do:** Check that the file is a `.pcap` or `.pcapng` capture (gzip compression is fine), as the message lists. Convert a file in another format first.

**Exit code:** None. The error goes back to the program that calls the library.

### `not a SIP message: first line is '{line}'`

Library parser error: the first line neither starts with `SIP/2.0 ` (a response) nor ends with ` SIP/2.0` (a request). So the data is not a SIP message.

- `{line}` is that line without its leading spaces.
- In the `sipnab` program, sipnab drops a SIP-looking packet that fails this way. It logs it only at debug level (`SIPNAB_LOG=debug`) as `SIP parse error:` followed by this text.
- `-x`/`--quiet-bad-parse` silences that line.

**What to do:** The input is not SIP 2.0. On the command line, `-x`/`--quiet-bad-parse` hides the debug line for such packets.

**Exit code:** None. The error goes back to the program that calls the library.

### `no transport header (not UDP/TCP)`

Packet decoder error from the library: the IP packet carries IGMP (multicast group management). It does not carry a transport that sipnab reads, such as UDP or TCP.

- In the `sipnab` program this text appears only in debug logging (`SIPNAB_LOG=debug`). It is on a line that starts with `Skipping` and ends with this text.
- sipnab counts the frame in the headless (`-N`) end-of-run `NOT DECODED` summary, and in the `sipnab_capture_undecodable_frames_total` metric. The run continues.

**What to do:** You need to do nothing. IGMP carries no SIP or RTP.

**Exit code:** None. The error goes back to the program that calls the library, and a `sipnab` run skips the frame and continues.

### `RTP version {version}, expected 2`

Library parser error from `parse_rtp_header`. The two version bits at the start of the RTP header do not hold 2. RTP (Real-time Transport Protocol) carries call audio.

- `{version}` is the value found.
- In the `sipnab` program, the RTP detector treats such a UDP packet as not RTP. It drops any half-detected stream for that address pair, without printing anything.

**What to do:** The input is not an RTP version 2 packet. Library callers should pass only the UDP payload of an RTP packet, starting at the RTP header.

**Exit code:** None. The error goes back to the program that calls the library.

### `SDP must start with a v= line`

Library parser error from `parse_sdp`. SDP (Session Description Protocol) is the part of a SIP message that describes the media.

- The first non-blank line of the SDP body does not begin with `v=`. Or the body holds only blank lines.
- In the `sipnab` program, sipnab does not use a SIP message body that fails this way for media setup. It prints no message.

**What to do:** The SDP body has the wrong form. It must start with a `v=0` line.

**Exit code:** None. The error goes back to the program that calls the library.

### `{what} too short: {got} bytes (need {need})`

Data is shorter than the structure it must hold.

- `{what}` names the structure.
- `{got}` is the number of bytes available.
- `{need}` is the number of bytes required.
- The meaning depends on what reports it:
  - The RTP parser (`RTP header`, `RTP CSRC list`, `RTP extension header`, `RTP extension payload`): the RTP detector silently treats the packet as not RTP.
  - The capture reader (`capture file`, `pcap global header`, `pcapng section header`): it comes from the library function `PcapReader::new`.
  - The packet decoder (headers such as `Linux SLL packet` or `GRE header`): sipnab counts the frame as truncated in the headless (`-N`) end-of-run `NOT DECODED` summary.

**What to do:** For truncated frames, capture again with a larger `--snaplen`. For a capture file or RTP packet, the input ends early or is not in that format.

**Exit code:** None. The error goes back to the program that calls the library, or sipnab counts the frame as truncated, and the run continues.

### `unsupported GRE inner protocol: 0x{0:04X}`

Packet decoder error from the library: a GRE tunnel packet carries an inner protocol other than IPv4, IPv6 or Transparent Ethernet Bridging (`0x6558`).

- `{0}` is the protocol type in hex.
- In the `sipnab` program this text appears only in debug logging (`SIPNAB_LOG=debug`). It is on a line that starts with `Skipping` and ends with this text.
- sipnab counts the frame in the headless (`-N`) end-of-run `NOT DECODED` summary, and in the `sipnab_capture_undecodable_frames_total` metric. The run continues.

**What to do:** The run needs nothing from you. sipnab does not decode traffic inside that tunnel type.

**Exit code:** None. The error goes back to the program that calls the library, and a `sipnab` run skips the frame and continues.

### `unsupported IP protocol number: {0}`

Packet decoder error (library surface). The packet's IP protocol number names a payload that sipnab does not read as a transport.

- `{0}` is that number.
- It occurs for:
  - an IP payload with no UDP, TCP or SCTP header that sipnab can slice;
  - ESP (protocol 50) that is not readable null-encrypted ESP;
  - an Authentication Header that protects something other than UDP or TCP;
  - a HEP-delivered packet whose stated protocol maps to no SIP transport.
- In the `sipnab` program, this text appears only in debug logging (`SIPNAB_LOG=debug`) as `Skipping unparseable packet: unsupported IP protocol number: {0}`.
- sipnab counts the frame in the headless (`-N`) end-of-run `NOT DECODED` summary, and in the `sipnab_capture_undecodable_frames_total` metric. The run continues.

**What to do:** The run needs no action. The headless (`-N`) end-of-run summary lists the protocol numbers it skipped as `no transport (IP protocol N)`.

**Exit code:** None. This is a warning, and the run continues.

### `unsupported link type: {0}`

Packet decoder error (library surface). sipnab does not decode the capture's link-layer header type.

- The link-layer header type is the DLT number. It tells the reader how each frame starts.
- `{0}` is that number.
- sipnab supports Ethernet, Linux cooked capture v1 and v2, raw IP, PPP and BSD loopback.
- In the `sipnab` program, every frame of such a capture fails this way.
- The headless (`-N`) end-of-run summary reports `unsupported link type <N>`, and the run continues.

**What to do:** Capture on an interface, or with a capture tool setting, that produces one of the supported link types.

**Exit code:** None. This is a warning, and the run continues.

### `unsupported SDP version: '{version}'`

Library parser error from `parse_sdp`. The SDP `v=` line gives a version other than `0`.

- `{version}` is the text after `v=`.
- In the `sipnab` program, sipnab does not use a SIP message body that fails this way for media setup. It prints no message.

**What to do:** The sender produced a malformed SDP body. Its first line must be `v=0`.

**Exit code:** None. The error goes back to the program that calls the library.