Troubleshooting

mountOS diagnoses itself. The client ships a check command that verifies every mount backend and prints the fix when one fails, every service and mount carries a live dashboard, the HUB collects alerts, and failures land in the logs with the cause named.

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, covering 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. A failing backend prints its own diagnostic steps, 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's full reference is built in as well. mountos man prints the manual page, formatted when nroff is available, and every command documents itself with --help.

Watch it live

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

Let an AI agent troubleshoot

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

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 and never mutates state. Paired with the published agent skill at skill.md, questions like why a mount is slow or what was deleted yesterday are answered from live data.

When a cluster stays not ready

The one failure whose symptom shows up far from its cause. A misconfigured service starts, refuses to register, and keeps retrying, so the volume's cluster never turns ready. The service's own log names the mismatch.

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

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

Listing a huge directory feels slow

A mountOS directory read returns entries together with their attributes, so 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 doubles as input for the version and recovery tooling.

Read the log, it names the fix

Failures are designed to be loud and specific. A service that cannot boot lists the exact environment variables it is missing. 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 a session cannot be established. Client logs live under ~/.mountOS/logs/ on macOS and Linux and %LOCALAPPDATA%\mountOS on Windows, and mountos check prints the platform log queries next to each backend.

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