stamparm/maltrail · error · ConfigError

missing 'USER_WHITELIST' file

Error message

missing 'USER_WHITELIST' file '{}'

What it means

When USER_WHITELIST names a whitelist file (a non-empty, non-comma value), the loader normalizes it relative to the config root and requires it to exist as a regular file (p.is_file()). If it does not, the loader bails with this message showing the resolved path.

Solutions

1. Create the whitelist file at the path shown in the error, or fix the USER_WHITELIST value to point at the real file.
2. Check how the path resolves: it is normalized against the config root (resolve_root), so use an absolute path or verify the config file's location.
3. Ensure the path is a regular file, not a directory.
4. If provisioning, guarantee the file exists before the sensor starts (touch it with correct ownership).

Example fix

// before (config.conf)
USER_WHITELIST=whitelist.txt   // file not present next to config

// after (config.conf) + create file
USER_WHITELIST=/etc/sensor/user_whitelist.txt
# $ touch /etc/sensor/user_whitelist.txt

let p = normalize_path(&root, &get_str(&raw, "USER_WHITELIST"));
if !get_str(&raw, "USER_WHITELIST").is_empty() && !p.is_file() {
    eprintln!("USER_WHITELIST file does not exist: {}", p.display());
}

When it happens

Trigger: USER_WHITELIST set to a path that does not exist or is a directory: typo in the filename, file deleted, wrong relative path given the config root resolution, or pointing at /etc/passwd-style directories instead of a file.

Common situations: Copying a config between hosts without copying the whitelist file; running the sensor from a different working directory so the relative path resolves elsewhere; provisioning scripts that create the whitelist only on first boot; SELinux/NFS mounts hiding the file.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• missing 'USER_IGNORELIST' file
• invalid USERS entry ' ' [?] (hint: add whitespace at start…
• invalid configuration
• missing configuration file
• missing mandatory option

AI-assisted analysis of stamparm/maltrail@77cfb06d76 (2026-09-13). Data as JSON: /api/errors/9e8908fccaf5544f. Report an issue: GitHub.

Appendix: source

Thrown at sensor/src/config.rs:814

            bail!("invalid configuration value for 'REMOTE_SEVERITY_REGEX' ('{remote_severity_regex}')");
        }

        let update_period = match get_u64(&raw, "UPDATE_PERIOD") {
            Some(v) => v,
            None => bail!("invalid configuration value for 'UPDATE_PERIOD' ('{}')", get_str(&raw, "UPDATE_PERIOD")),
        };

        let user_whitelist = {
            let v = get_str(&raw, "USER_WHITELIST");
            if v.is_empty() {
                None
            } else if v.contains(',') {
                crate::cprintln!("[x] configuration value 'USER_WHITELIST' has been changed. Please use it to set location of whitelist file");
                None
            } else {
                let p = normalize_path(&root, &v);
                if !p.is_file() {
                    bail!("missing 'USER_WHITELIST' file '{}'", p.display());
                }
                Some(p)
            }
        };
        let user_ignorelist = {
            let v = get_str(&raw, "USER_IGNORELIST");
            if v.is_empty() {
                None
            } else {
                let p = normalize_path(&root, &v);
                if !p.is_file() {
                    bail!("missing 'USER_IGNORELIST' file '{}'", p.display());
                }
                Some(p)
            }
        };

        let trails_file = {

View on GitHub (pinned to 77cfb06d76)