Skip to main content
← Back to list
01Issue
BugShippedSwamp CLIPublicTeam
Assigneeszack

Relationships

#4671 Datastore fails to open on fresh checkout: early vault service never auto-resolves the datastore-auth vault's extension type

Opened by kneel · 11/12/2026· Shipped 11/12/2026

Datastore fails to open on a fresh checkout when the datastore-auth vault uses an extension vault type (early vault service never auto-resolves the vault type)

Summary

When a repository's datastore config reads its credential from a vault (vault.get(<vault>, <key>)) and that vault's type is provided by an extension (e.g. an @scope/pass type) rather than a built-in type (local_encryption), a fresh checkout/worktree/clone cannot open the datastore.

The early (pre-datastore) vault service that resolves the datastore config only registers vaults whose type bundle is already cached under .swamp/vault-bundles/. Unlike the canonical vault loader, it never auto-resolves a missing vault-type extension. The datastore type itself is auto-resolved, so it installs fine -- but the vault type needed to read the datastore's own credential is skipped, the auth vault fails to register, and the datastore never opens.

Environment

  • swamp 20261111.234122.0-sha.cd35f58c (also reproduced on ...001635...).
  • Linux x86_64 (not platform-specific; the trigger is the empty .swamp/).
  • Datastore: an extension datastore type whose config reads its credential via vault.get(<authVault>, <key>), where <authVault>'s type is an extension vault type. datastore.managedConfig is unset/false (see note below).
  • .swamp/ is gitignored, so git worktree add / a fresh clone starts with an empty .swamp/ and no cached vault-type bundles.

Reproduction

  1. A repo whose .swamp.yaml datastore block reads its credential from an extension-typed vault:

    datastore:
      type: "@example/blob-datastore"
      config:
        auth:
          connectionString: "${{ vault.get(dsauth, CONNECTION_STRING) }}"

    with the auth vault definition tracked in the repo's vaults/ dir, e.g. vaults/@example/pass/<uuid>.yaml:

    name: dsauth
    type: "@example/pass"
    config: { prefix: "example/dsauth" }

    (@example/pass is an extension vault type; its bundle is NOT a built-in.)

  2. git worktree add ../wt -b wt main -- fresh, empty .swamp/ (so .swamp/vault-bundles/ does not exist).

  3. In the worktree, run any datastore-backed command, e.g. swamp data query '<predicate>' --json.

Expected

The datastore opens: swamp auto-resolves dsauth's vault-type extension (subject to trustedCollectives), exactly as it already auto-resolves the datastore type, and exactly as the canonical vault loader already does.

Actual

The datastore cannot open. With only the extension-typed dsauth present, zero vaults register, so the surfaced error is the empty-set branch:

Failed to resolve vault expression in datastore config: Vault 'dsauth' not found. No vaults are configured.

(If the repo also has built-in local_encryption vaults, those DO register and the message instead lists them: Vault 'dsauth' not found. Available vaults: <the local_encryption vaults only> -- every extension-typed vault is still absent.)

The true cause is emitted separately, one log line earlier, at warn:

Vault 'dsauth' not available for datastore config expressions: Unsupported vault type: '@example/pass' (vault 'dsauth'). Available vault types: <...>

So the fatal error says "not found" (pointing at a missing vault definition, which is wrong -- the def is present and git-tracked), while the real cause ("unsupported/uninstalled vault type") is only in a non-fatal warn line, and neither message tells the user to swamp extension pull <type>.

Root cause

src/cli/datastore_expression_resolver.ts:

  • createEarlyVaultService(repoDir) builds the vault service used to resolve the datastore config's vault.get(...) before the datastore exists. It calls loadCachedVaultBundles(repoDir) (~lines 48-94), which only imports vault-type bundles already present under .swamp/vault-bundles/. There is no auto-resolution of a missing vault-type extension.
  • It then reads each vault def from the git-tracked vaults/ dir and calls registerVault(...) per def (~lines 116-132). For a def whose type is an uncached extension type, createVaultProvider hits its default branch and throws Unsupported vault type: '<type>' (vault '<name>'). (src/domain/vaults/vault_provider_factory.ts:73). The loop catches it and skips that vault, logging at warn (datastore_expression_resolver.ts:128-131).
  • Net: every extension-typed vault is dropped whenever its bundle isn't already cached. The datastore-auth vault is dropped on a fresh checkout, so service.get(<authVault>, ...) throws one of the "not found" branches (src/domain/vaults/vault_service.ts:323 empty / :334 non-empty).

This is a stripped reimplementation of the canonical loader. The normal path, VaultService.fromRepository (src/domain/vaults/vault_service.ts:169-174), does exactly the missing step:

await vaultTypeRegistry.ensureTypeLoaded(vaultType);
if (!vaultTypeRegistry.has(vaultType) && vaultType.startsWith("@")) {
  await resolveVaultType(vaultType, getAutoResolver());
}

createEarlyVaultService omits that resolveVaultType(...) call, so the early (datastore-bootstrap) path can't install a vault type the normal path would.

The asymmetry is also visible against the datastore type: resolve_datastore.ts auto-resolves the datastore type via resolveDatastoreType(dsType, autoResolver) (~lines 446-447), but nothing performs the equivalent for the vault type the datastore's own credential depends on.

Because .swamp/vault-bundles/ is gitignored and per-checkout, this bites every fresh clone/worktree, not just a first-ever setup.

Impact

  • Any repo whose datastore-auth vault uses an extension vault type cannot bootstrap a fresh clone or git worktree -- the datastore simply won't open.
  • Misleading: the fatal error says "Vault not found" (implying a missing def) while the def is present and tracked; the real cause (uninstalled vault type) is only in a separate warn line and never suggests swamp extension pull.

Suggested fix

In createEarlyVaultService (datastore_expression_resolver.ts), mirror VaultService.fromRepository: after ensureTypeLoaded, if a vault def's type is an uncached @-extension type, call resolveVaultType(type, getAutoResolver()) (honoring trustedCollectives) -- the primitive already exists at src/domain/extensions/extension_auto_resolver.ts:711-721 and honors allowedCollectives, exactly like resolveDatastoreType. At minimum, resolve the vault type(s) referenced by the datastore config's vault.get(...) expressions before/while building the early vault service. No new trust surface: the datastore extension is already installed and executed at this stage.

Implementation caveat: auto-resolution emits progress JSON to stdout, which can corrupt --json output (see the note at resolve_datastore.ts:441-443, which calls ensureLoaded() first to avoid exactly this). Any vault auto-resolve added to the early path must route that progress output the same way.

Secondary (cheap, independent): make the surfaced error distinguish "vault def not found" from "vault type bundle not installed (run swamp extension pull <type>)", so the fatal message names the real cause instead of only the warn line.

Workaround

In the affected checkout, pre-cache the bundles:

swamp extension pull <datastore-type-extension>
swamp extension pull <auth-vault-type-extension>

This caches both bundles under .swamp/, after which the datastore opens normally. No datastore write and no vault re-creation is involved -- the vault defs are already tracked in vaults/. (Explicit pull does not require the collective to be trusted; trust only gates auto-resolve.)

Note: managedConfig

This bug applies only when datastore.managedConfig is unset/false. If it is truthy, vault.get(...) in datastore config is refused outright (datastore_expression_resolver.ts:145-153) with a message directing you to env vars, so the early vault service is never built.

02Bog Flow
✓OPEN✓TRIAGED✓IN PROGRESS✓SHIPPED+ 1 MOREASSIGNED+ 2 MOREREVIEW+ 8 MOREPR_LINKED+ 2 MORESESSION_SUMMARIZED

Shipped

11/12/2026, 2:25:06 PM

Click a lifecycle step above to view its details.

03Sludge Pulse
kneel moved this from a private collective to public11/12/2026, 4:13:40 AM
zack assigned zack11/12/2026, 1:19:48 PM
Editable. Press Enter to edit.

zack commented 11/12/2026, 2:25:07 PM

Thanks @kneel for reporting this! We shipped: Make the datastore bootstrap vault service work on a fresh checkout when the datastore-auth vault uses an extension vault type: install the Zod global before importing cached vault bundles, auto-resolve the missing extension type of the vault named in a vault.get (lazily, honouring trustedCollectives and installed-only callers, never touching the vault registry loader), and replace the misleading Vault not found error with one naming the uninstalled type and the swamp extension pull command.. The fix has been merged and a release is on its way. We appreciate your contribution to swamp.

Sign in to post a ripple.