What causes "geoip: failed to stat database '{}': {}" in netdata/netdata?

Confirm the path exists at the moment of the error: ls -l and stat

netdata/netdata · error · anyhow::Error

geoip: failed to stat database '{}': {}

Error message

geoip: failed to stat database '{}': {}

What it means

read_geoip_file_signature calls fs::metadata on each configured GeoIP database to build a change-detection signature (mtime + size). For a required database, any metadata failure (usually ENOENT or EACCES) returns this error instead of a signature.

Source

Thrown at src/crates/netflow-plugin/src/enrichment/data/geoip/files.rs:60

            .collect::<Result<Vec<_>>>()?,
        geo: geo_paths
            .iter()
            .map(|path| read_geoip_file_signature(path, optional))
            .collect::<Result<Vec<_>>>()?,
    })
}

pub(crate) fn read_geoip_file_signature(
    path: &str,
    optional: bool,
) -> Result<Option<GeoIpFileSignature>> {
    let metadata = match fs::metadata(path) {
        Ok(metadata) => metadata,
        Err(_) if optional => {
            return Ok(None);
        }
        Err(err) => {
            return Err(anyhow::anyhow!(
                "geoip: failed to stat database '{}': {}",
                path,
                err
            ));
        }
    };

    let modified = match metadata.modified() {
        Ok(time) => time,
        Err(err) if optional => {
            tracing::warn!(
                "geoip: failed to read modification time for optional database '{}': {}",
                path,
                err
            );
            return Ok(None);
        }
        Err(err) => {

View on GitHub (pinned to 4864de85e2)

Solutions

Confirm the path exists at the moment of the error: ls -l <path> and stat <path>
Check parent-directory execute permissions for the netdata user
If the file is replaced during updates, point config at a stable path and atomically rename new files into place
Mark the database optional if transient absence is acceptable

Defensive patterns

Strategy: validation

Validate before calling

stat /usr/share/GeoIP/GeoLite2-ASN.mmdb || echo "cannot stat GeoIP DB - fix path/mount before starting agent"

Try / catch

Wrap enrichment startup: on stat failure, retry after a short delay (covers mounts settling) then report and run without GeoIP if configured optional.

Prevention

Keep mmdb files on local disk, not removable/network mounts
Use atomic replace during DB rotation so stat never sees a missing file
Add monitoring on the DB path (file exists check)

When it happens

Trigger: A required GeoIP database path that cannot be stat'ed: file removed between config check and signature read, path on an unmounted network share, or directory traversal denied. Optional databases skip the signature with Ok(None) instead.

Common situations: Database deleted or rotated (GeoLite2 update scripts that replace files) while the agent runs; NFS/SMB mount drops; symlink to a missing target; path with a missing parent directory.

Related errors

AI-assisted analysis of netdata/netdata@4864de85e2 (2026-08-15). Data as JSON: /api/errors/61cdaf8bcca237de. Report an issue: GitHub.