pfs doctor

Run health checks to validate configuration and runtime state.

Usage

pfs doctor              # check all mounts
pfs doctor <mount>      # check a specific mount
pfs doctor <mount> <path>  # inspect a specific file

Scope levels

Global (pfs doctor): Validates the config file and runs health checks for every mount defined in the config.

Mount (pfs doctor <mount>): Runs checks for a single mount, including config validation, storage path accessibility, daemon status, index stats, pending events, and disk access analysis.

When a JSON log file is configured (via log.file or PFS_LOG_FILE), doctor also scans recent log entries for FUSE permission errors. This requires JSON logs (log.format: json). To avoid stale one-off errors, only recent entries (last ~15 minutes, and after the most recent mount ready for that mount when present) are reported.

File inspect (pfs doctor <mount> <path>): Inspects a specific virtual path across all storages, showing index metadata, pending events, and (optionally) physical disk state.

By default, file inspect does not touch storage paths configured with indexed: true, even when the path is absent from the index database. This prevents spinning up HDDs; the index remains the source of truth for indexed storage. To check for out-of-band files or force an on-disk stat across all storages, pass --disk.

Exit codes

Code	Meaning
0	All checks passed (or file inspect succeeded).
78	Validation errors or issues found.

Examples

# Check everything
pfs doctor

# Check a specific mount
pfs doctor media

# Inspect a specific file across all storages
pfs doctor media library/movies/MovieA/MovieA.mkv

Shell completion

pfs doctor supports tab completion for mount names and virtual paths. Virtual path completion uses the index database, with a fallback to non-indexed storage for paths not in the index.