Summary
When engram serve fails to mount a vault because the per-user name: differs from the per-vault vault_name:, the error hint reads:
Hint: vault at <path> has its own vault_name in engram.config.yaml that likely differs from <name>; run 'engram doctor' to detect the mismatch.
But engram doctor does NOT include a vault-name-mismatch check. Following the hint produces a clean doctor output even when the mismatch is the actual cause.
Reproduction
# ~/.config/engram/config.yaml
default_user: someuser
vaults:
- name: foo # per-user name
path: ~/vaults/myvault
role: primary
# ~/vaults/myvault/engram.config.yaml
vault_name: bar # per-vault name -- differs from "foo"
$ engram serve
ERROR: could not mount 'foo'. Hint: vault at ~/vaults/myvault has its own
vault_name in engram.config.yaml that likely differs from 'foo'; run
'engram doctor' to detect the mismatch.
$ engram doctor
# (no check fires for the mismatch)
Expected
Either:
- (a) Add a
vault_name_alignment check to engram doctor that compares per-user name: against per-vault vault_name: for each registered vault, OR
- (b) Remove the misleading hint from the
engram serve error path.
(a) is the more user-friendly option since engram doctor is the natural place to ask "is my config sane?"
Context
Surfaced during a multi-vault registry mount failure on 2026-05-16. The hint cost ~20 minutes of debugging (assumed doctor would surface the issue, ran it twice, eventually traced through the multivault registry code to find the actual cause). Fix: aligned per-user name: memex -> name: engram-vault to match the per-vault vault_name: engram-vault.
Related to (but distinct from) the multi-vault "same path, different name" issue filed separately.
Summary
When
engram servefails to mount a vault because the per-username:differs from the per-vaultvault_name:, the error hint reads:But
engram doctordoes NOT include a vault-name-mismatch check. Following the hint produces a clean doctor output even when the mismatch is the actual cause.Reproduction
Expected
Either:
vault_name_alignmentcheck toengram doctorthat compares per-username:against per-vaultvault_name:for each registered vault, ORengram serveerror path.(a) is the more user-friendly option since
engram doctoris the natural place to ask "is my config sane?"Context
Surfaced during a multi-vault registry mount failure on 2026-05-16. The hint cost ~20 minutes of debugging (assumed doctor would surface the issue, ran it twice, eventually traced through the multivault registry code to find the actual cause). Fix: aligned per-user
name: memex->name: engram-vaultto match the per-vaultvault_name: engram-vault.Related to (but distinct from) the multi-vault "same path, different name" issue filed separately.