Troubleshooting

mountOS diagnoses itself. The client includes a check command. This command verifies every mount backend and prints the fix when one fails. Every service and mount has a live dashboard. The HUB collects alerts. Each log entry names the cause of the failure.

Start with mountos check

mountos check verifies the mount backends on the machine it runs on. On macOS it checks FSKit, macFUSE, NFS, and SMB. For each backend, it checks the OS version, framework availability, app installation, and extension registration and enablement. On Linux it checks io_uring readiness for FUSE, kernel version, config, and module parameters. On Windows it checks the mountosio kernel driver.

mountos check

  Backend       Status
  ────────────  ──────
  FSKit         ~ Capable
  macFUSE       ✓ Supported
  NFS           ✓ Supported
  SMB           ✓ Supported

FSKit:
  ✗ FSKit extension: registered but not enabled,
    enable it in System Settings > General > Login Items & Extensions

  Diagnostic steps:
    Open host app (required once for extension registration):
      open /Applications/mountOSFSKit.app
    ...

The example above is a trimmed macOS run. When a backend fails, it prints its own diagnostic steps. The output lists the exact commands to re-register an extension, the log locations, and the system log queries to run.

mountos check --fskit          # one backend (macOS)
mountos check --io-uring       # io_uring readiness (Linux)
mountos check --json           # machine-readable, for automation

The client includes its full reference. The mountos man command prints the manual page. It formats the page when nroff is available. Every command also documents itself with the --help flag.

Watch it live

Every mount ships a dashboard. Run mountos dashboard <mount-path> for a terminal view, or add --gui for a browser view. The dashboard shows throughput, cache, open files, and session detail. Every service carries the same feature. Run <service> dashboard on a node.

Let an AI agent troubleshoot

Every mount also exposes a local, read-only MCP connector. Register it once. After that, any MCP-capable assistant on the machine can query running mounts directly. It serves a mount's identity, live stats, and throughput. It also serves recent deletions, recovered files, configuration, diagnostics, file version history, and the CLI commands that operate the mount.

mountos mcp install   # registers with Claude Desktop, Claude Code, Codex, and Gemini
mountos mcp status    # shows where it is registered

The connector is safe on production mounts. It never reads file contents. It never mutates state. An AI agent that uses the connector and the published agent skill at skill.md can answer questions from live data. Example questions include why a mount is slow and what was deleted yesterday.

When a metadata cluster stays not ready

This is the one failure type whose symptom appears far from its cause. A misconfigured service starts but refuses to register. It keeps retrying. As a result, the volume's metadata cluster never becomes ready. The service's own log names the mismatch.

discovery registration deferred; will retry,
  error: "metadata cluster 7f3a... belongs to region 2, but service is configured for region 1",
  retry_interval: 1m0s

Fix the topology. The next retry picks it up. A fix in the admin plane, such as reactivating a metadata cluster, needs no restart. A fix to the service's environment needs a restart. When the HUB receives a registration request and rejects it, the HUB raises a critical topology alert. The alert appears in the dashboard's alerts view. The nodes view shows what registered where.

Listing a huge directory feels slow

A mountOS directory read returns entries together with their attributes. As a result, flags that print per entry stream at full speed. Plain ls buffers the whole directory to lay out columns before printing anything.

ls -ioFs1 /mnt/ws/big-directory

The inode column also serves as input for the version and recovery tooling.

Read the log, it names the fix

Every failure message is loud and specific. A service that cannot start lists the exact environment variables that it lacks. The license line states its dates and stages. The db commands say whether a database needs install or migrate. The client prints a connect checklist when it cannot establish a session. The client stores its logs under ~/.mountOS/logs/ on macOS and Linux, and under %LOCALAPPDATA%\mountOS on Windows. The mountos check command prints the platform log queries next to each backend.

For anything the tooling does not explain, contact support@mountos.io.