multi_user_template_create: improve preflight + error UX when /home is not btrfs #150

New issue

Closed

opened 2026-04-28 06:28:03 +00:00 by mahmoud · 2 comments

mahmoud commented

2026-04-28 06:28:03 +00:00

Owner

Split out from #135.

Symptom

On a fresh Ubuntu/Debian machine, the very first command an operator runs from the multi-user setup docs (multi_user_template_create) hard-fails at step [1/12] preconditions:

=== Template user: create ===
→ [1/12] preconditions
Error: nu::shell::error
  × /home is on ext4, expected btrfs.
     ╭─[/home/.../tools/modules/installers/lib.nu:119:20]
 118 │     if $fs != "btrfs" {
 119 │         error make {msg: $"($path) is on ($fs), expected btrfs."}
     ╰────

Why this is a problem

The check itself is correct — multi_user_template_create legitimately requires /home to be a btrfs subvolume so it can lay down per-user nested subvolumes for the snapshot/swap flow (see tools/docs/template.md:9). But the failure surfaces a few real UX gaps:

No upstream guidance. A fresh Ubuntu/Debian install has /home on ext4 by default. Operators following onboarding hit this with their first non-trivial command, with no warning earlier in the flow.
The error has no remediation. It tells the user the filesystem is wrong but offers no path forward — no "reformat /home as btrfs" recipe, no link to tools/docs/template.md, no mention that this is multi-user-template-only and that other onboarding flows don't need it.
No escape hatch. Single-user dev installs don't need template snapshots, but there's no flag to skip the btrfs requirement and get a degraded-but-functional template (or to bail out cleanly with a recommendation to skip the multi-user flow entirely).

Suggested directions (cheap → invasive)

Better error text in tools/modules/installers/lib.nu:109-121 — include the why, link to tools/docs/template.md, and tell the operator that single-user installs can skip multi_user_template_create entirely.
Hero_running / onboarding doc preflight — surface the btrfs requirement before the user invokes multi_user_template_create, e.g. as part of the hero_running skill flow.
Optional --allow-non-btrfs flag with a loud warning, for dev installs that want to exercise the rest of the flow on ext4 (no snapshot guarantees).

My preference is (1) + (2) as a small follow-up, and to defer (3) until someone actually needs it.

Files

tools/modules/installers/lib.nu:109-121 — require_btrfs definition.
tools/modules/installers/template.nu:61-67 — call site at step [1/12].
tools/docs/template.md, tools/docs/multiuser.md — context for the requirement.

Split out from #135. ## Symptom On a fresh Ubuntu/Debian machine, the very first command an operator runs from the multi-user setup docs (`multi_user_template_create`) hard-fails at step `[1/12] preconditions`: ``` === Template user: create === → [1/12] preconditions Error: nu::shell::error × /home is on ext4, expected btrfs. ╭─[/home/.../tools/modules/installers/lib.nu:119:20] 118 │ if $fs != "btrfs" { 119 │ error make {msg: $"($path) is on ($fs), expected btrfs."} ╰──── ``` ## Why this is a problem The check itself is correct — `multi_user_template_create` legitimately requires `/home` to be a btrfs subvolume so it can lay down per-user nested subvolumes for the snapshot/swap flow (see `tools/docs/template.md:9`). But the failure surfaces a few real UX gaps: 1. **No upstream guidance.** A fresh Ubuntu/Debian install has `/home` on ext4 by default. Operators following onboarding hit this with their first non-trivial command, with no warning earlier in the flow. 2. **The error has no remediation.** It tells the user the filesystem is wrong but offers no path forward — no "reformat /home as btrfs" recipe, no link to `tools/docs/template.md`, no mention that this is *multi-user-template-only* and that other onboarding flows don't need it. 3. **No escape hatch.** Single-user dev installs don't need template snapshots, but there's no flag to skip the btrfs requirement and get a degraded-but-functional template (or to bail out cleanly with a recommendation to skip the multi-user flow entirely). ## Suggested directions (cheap → invasive) 1. **Better error text** in `tools/modules/installers/lib.nu:109-121` — include the *why*, link to `tools/docs/template.md`, and tell the operator that single-user installs can skip `multi_user_template_create` entirely. 2. **Hero_running / onboarding doc preflight** — surface the btrfs requirement *before* the user invokes `multi_user_template_create`, e.g. as part of the `hero_running` skill flow. 3. **Optional `--allow-non-btrfs` flag** with a loud warning, for dev installs that want to exercise the rest of the flow on ext4 (no snapshot guarantees). My preference is (1) + (2) as a small follow-up, and to defer (3) until someone actually needs it. ## Files - `tools/modules/installers/lib.nu:109-121` — `require_btrfs` definition. - `tools/modules/installers/template.nu:61-67` — call site at step `[1/12]`. - `tools/docs/template.md`, `tools/docs/multiuser.md` — context for the requirement.

mahmoud referenced this issue

2026-04-28 06:28:31 +00:00

Error during setup on a fresh machine #135

mahmoud commented

2026-04-28 07:18:28 +00:00

Author

Owner

Picking this up. Planned scope is small:

Rewrite the error in tools/modules/installers/lib.nu require_btrfs so it explains why btrfs is required, names the multi-user/snapshot flow, and links to tools/docs/template.md.
Mirror the same wording in tools/modules/installers/multiuser.nu multi_user_install (same check, second surface).
Update the [1/12] preconditions label in tools/modules/installers/template.nu so the requirement is named before the check runs.

No new flags. No doc-preflight changes (deferred — keeps the diff focused). PR will follow.

Picking this up. Planned scope is small: - Rewrite the error in `tools/modules/installers/lib.nu` `require_btrfs` so it explains *why* btrfs is required, names the multi-user/snapshot flow, and links to `tools/docs/template.md`. - Mirror the same wording in `tools/modules/installers/multiuser.nu` `multi_user_install` (same check, second surface). - Update the `[1/12] preconditions` label in `tools/modules/installers/template.nu` so the requirement is named before the check runs. No new flags. No doc-preflight changes (deferred — keeps the diff focused). PR will follow.

mahmoud referenced this issue

2026-04-28 07:18:30 +00:00

Error during setup on a fresh machine #135

mahmoud referenced this issue from a commit

2026-04-28 07:52:12 +00:00

fix(installers): explain why btrfs is required when /home check fails

mahmoud referenced this issue from a pull request that will close it,

2026-04-28 07:54:38 +00:00

fix(installers): explain why btrfs is required when /home check fails #152

mahmoud commented

2026-04-28 07:57:07 +00:00

Author