Skip to content

engram doctor: vault-name-mismatch check missing despite serve-time hint promising it #1

Description

@kpachhai

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions