> ## Documentation Index
> Fetch the complete documentation index at: https://filetrace.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Exit codes of filetrace and filetrace-agent

> Exit codes of the filetrace commands, doctor, agent status, stats and filetrace-agent, the codes systemd does not restart on, and how to script code 9.

Both programs report their outcome through the exit code, so that scripts, monitoring checks and service managers can act on it without parsing text. This page lists the codes of the `filetrace` commands, the special meanings that `doctor`, `agent status` and `stats` give them, and the codes of `filetrace-agent` with the ones its systemd unit does not restart on. Code 9 deserves the most attention: the command succeeded, but its answer may be incomplete.

## filetrace commands

| Code | Meaning | Typical cause |
| - | - | - |
| `0` | Success | |
| `1` | General error | The agent speaks a different protocol version; the file named with `--output` cannot be written; out of memory |
| `2` | Invalid arguments | An unknown option or command, a missing or malformed value, an invalid `--path-regex` |
| `3` | Permission denied | The agent's socket is not accessible to this user |
| `4` | Agent unavailable | No agent is serving the socket, or the connection to it was lost |
| `5` | Unsupported platform or capability | The kernel or platform cannot be monitored; a `--method` this build does not observe |
| `6` | Invalid configuration | The configuration file cannot be read or does not parse |
| `9` | Partial results | Events were lost inside the queried time range |

Errors are written to standard error. A usage error (code 2) ends with a pointer to the command's help:

```text theme={null}
See 'filetrace help files' for usage.
```

### 3: permission denied

The agent's socket admits only root and the agent's own user. With the agent running as root, the commands that query it need `sudo`:

```text theme={null}
Permission denied.

The agent socket /run/filetrace/agent.sock is not accessible to this user.
Run the command with sudo.
```

### 4: agent unavailable

The message names the socket and the reason the connection failed:

```text theme={null}
The Filetrace agent is not running (/run/filetrace/agent.sock: No such file or directory).

Start it with:
  sudo filetrace agent run

To check what this machine supports:
  sudo filetrace doctor
```

`filetrace watch` and `filetrace events --follow` do not fail this way: without an agent they collect in the foreground for as long as they run.

### 5: unsupported

Besides an unsupported kernel or platform, code 5 answers a question this build cannot answer. `--method splice`, `--method mmap` and `--method io_uring` are accepted by `files` and `transfers` and refused with code 5, rather than answered with an empty list that would read as "nothing was sent this way":

```text theme={null}
filetrace: transfers made with splice are not observed by this build, so none
can be listed. 'filetrace capabilities' shows what is observed.
```

### 6: invalid configuration

Every command except `config` and `help` reads the configuration file first, and stops with code 6 when the file cannot be read or does not parse. `filetrace config validate` reports the problem; it exits with 0 when the file is usable and 6 when it is not. See [Configuration file reference](https://filetrace.mintlify.site/reference/configuration.md#validation).

### 9: partial results

Code 9 means the command printed its answer, but events were lost inside the queried time range, so byte counts or records may be missing. The output on standard output is complete and well-formed in every format; the warning goes to standard error:

```text theme={null}
WARNING: <n> events lost.

Affected monitoring window:
<first> - <last>

Attribution reliability:
DEGRADED
```

A transfer during which events were lost is marked `incomplete: true` in JSON and with `*` after its confidence in tables. Lost events are also counted by `watch`, `stats` and `doctor`. `filetrace events --follow` exits with 0 when it is interrupted, whatever was lost while it ran.

## Commands with their own meanings

### doctor

`filetrace doctor` exits with the code of its verdict, also printed as `STATUS:` and, with `--json`, as `status`:

| Code | Status | Meaning |
| - | - | - |
| `0` | `READY` | The machine can be monitored |
| `3` | `NEEDS PRIVILEGES` | Loading BPF programs needs root, or `CAP_BPF` with `CAP_PERFMON` |
| `5` | `UNAVAILABLE` | This machine cannot be monitored |
| `9` | `DEGRADED` | Some probes are missing, or the running agent is losing events |

### agent status

| Code | Meaning |
| - | - |
| `0` | An agent is running and healthy |
| `4` | No agent is running (`Monitoring: STOPPED`) |
| `9` | An agent is running but degraded: it has lost events within the last minute |
| `3` | An agent is running, but its socket is not accessible to this user |

### stats

`filetrace stats` exits with 9 while the agent reports recent event loss, that is, a loss within the last minute. The JSON output shows the same condition as `"status": "degraded"`.

## filetrace-agent

`filetrace-agent` and `filetrace agent run` exit with these codes:

| Code | Meaning | Restarted by systemd |
| - | - | - |
| `0` | Stopped normally, by `SIGTERM`, `SIGINT` or `filetrace agent stop`, or not started because `[agent] enabled = false` | No |
| `1` | Other errors, such as another agent already serving the socket | Yes |
| `2` | Invalid arguments | No |
| `3` | Permission denied: the agent lacks the privileges to load BPF programs or to create its socket | No |
| `5` | Unsupported platform or kernel | No |
| `6` | Invalid configuration, including an exporter address of the wrong form (`[prometheus] listen`, `[otlp] endpoint`, `[grpc] listen`) | No |
| `8` | The metrics page cannot listen on `[prometheus] listen`, for example because the port is taken | Yes |

The systemd unit restarts the agent on failure after 5 seconds, at most 5 times in 300 seconds, except on the codes that a retry does not fix:

```ini theme={null}
Restart=on-failure
RestartSec=5
# Invalid arguments, missing privileges, an unsupported kernel and a broken
# configuration file do not go away on a retry.
RestartPreventExitStatus=2 3 5 6
```

The unit starts only where `/sys/kernel/btf/vmlinux` exists. Under OpenRC, the service checks for BTF and runs `filetrace config validate` before every start, and respawns the agent after 5 seconds, at most 5 times in 300 seconds. See [Run the agent as a service](https://filetrace.mintlify.site/guides/run-as-a-service.md).

## Scripting

Treat 9 as a result to keep, with a warning, rather than as a failure:

```bash theme={null}
#!/bin/sh
# Exports the last hour of file transfers; run as root.
filetrace files --since 1h --jsonl --output /var/tmp/transfers.jsonl
code=$?
case $code in
0)
    ;;
9)
    echo "events were lost in the last hour; byte counts may be low" >&2
    ;;
*)
    echo "filetrace files failed with exit code $code" >&2
    exit "$code"
    ;;
esac
```

A health check that tells a stopped agent from a degraded one:

```bash theme={null}
#!/bin/sh
filetrace agent status >/dev/null
case $? in
0) echo "OK: agent running" ;;
9) echo "WARNING: agent running, events lost in the last minute"; exit 1 ;;
4) echo "CRITICAL: agent not running"; exit 2 ;;
*) echo "UNKNOWN: agent status could not be read"; exit 3 ;;
esac
```

[Use Filetrace output in scripts](https://filetrace.mintlify.site/guides/automation.md) has more patterns.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.