Skip to main content
← Back to list
01Issue
BugShippedSwamp CLI
Assigneesstack72

Relationships

#1181 Unreachable path in .swamp-sources.yaml is fatal to every command, including 'swamp version'

Opened by magistr · 7/16/2026· Shipped 7/16/2026

A single unreachable path in .swamp-sources.yaml makes every swamp command fail — including commands that have nothing to do with extensions, such as swamp version and swamp quest. The repo becomes unusable until the stale entry is removed by hand.

The only commands that still work are swamp extension source list and swamp extension source rm, which is the sole escape hatch. Discovering that requires reading the error text carefully — and the error is emitted by commands where an extension source is not plausibly relevant, so the failure is surprising at the point of use.

Reproduction (clean repo, ~30 s)

swamp init repro-test
cd repro-test
swamp quest --json          # exit 0

# register a source, then make its path go away
mkdir -p /tmp/ghost/extensions/models
cat > /tmp/ghost/manifest.yaml <<'EOF'
manifestVersion: 1
name: "@test/ghost"
version: "2026.07.16.1"
description: ghost
models:
  - extensions/models/ghost.ts
EOF
echo 'export const model = {};' > /tmp/ghost/extensions/models/ghost.ts
swamp extension source add /tmp/ghost
rm -rf /tmp/ghost

swamp quest --json          # exit 1  <-- bricked

Observed blast radius

Every one of these exits 1 with the same error:

command exit
swamp version 1
swamp quest --json 1
swamp model search --json 1
swamp data query true --json 1
swamp vault list --json 1
swamp workflow list --json 1
swamp extension source list --json 0 (only survivor)

Error text:

Declared extension source(s) in .swamp-sources.yaml cannot be resolved:
  - /tmp/ghost

Remove stale entries with 'swamp extension source rm <path>' or fix the path.

swamp version failing is the clearest signal that this check runs too early and too broadly — it should not be possible for extension-source config to break printing a version string.

Why this matters in practice

A source path can become unreachable through entirely ordinary events, none of which involve the user editing config:

  • the extension lives on an unmounted external/network volume
  • the source sits in a deleted git worktree or a branch that was cleaned up
  • the directory was moved or renamed

In each case the whole CLI stops working, with no obvious connection between what the user did and what broke.

Probable regression

I hit this mid-session on a repo that had carried three stale source entries for some time without trouble.

  • 19:53 — swamp model validate <name> succeeded; the stale sources produced only a [WRN] swamp·sources: Source path does not exist: ... warning. CLI version 20260716.190954.0-sha.b479eb8a.
  • 19:55–~20:01 — dozens of swamp workflow run and swamp data query invocations succeeded against the same unchanged config.
  • ~20:01 — two independent loops (workflow runs and data queries) began failing simultaneously, with no change to .swamp-sources.yaml.
  • 20:08 — CLI version now reported 20260716.194319.0-sha.df9fc306; the same stale sources were fatal.

The config did not change across that window and no command of mine rewrote it, so the behaviour change appears to have arrived with the CLI update from b479eb8a to df9fc306. I could not run the older binary to confirm directly, so please treat the exact culprit commit as unverified — but the warning-to-fatal transition itself is reproducible on df9fc306 per the steps above.

Suggested fix

Restore the previous behaviour: warn on unresolvable sources and continue. If a hard failure is wanted, scope it to commands that actually need to resolve an extension type (model validate, model method run, workflow run), and let version, quest, vault, and data query proceed. Degrading to a warning also preserves the recovery path without requiring the user to know about extension source rm.

02Bog Flow
✓OPEN✓TRIAGED✓IN PROGRESS✓SHIPPED+ 1 MOREASSIGNED+ 2 MOREREVIEW+ 4 MOREPR_MERGED+ 1 MORECONTRIBUTOR_NOTIFIED

Shipped

7/16/2026, 8:58:36 PM

Click a lifecycle step above to view its details.

03Sludge Pulse
stack72 assigned stack727/16/2026, 8:15:35 PM
Editable. Press Enter to edit.

magistr commented 7/16/2026, 8:17:53 PM

Confirmed the real-world provenance of the stale entries in my case. It is more mundane than the scenarios I listed, which makes the sharp failure mode easier to hit than it first appears.

The three source directories were untracked extension work-in-progress living in a separate workspace repo. They were captured by git stash -u on a feature branch and never restored, so the directories vanished from the working tree. .swamp-sources.yaml lives outside that repo and kept pointing at them. Recovered them intact from stash@{N}^3.

The general shape is worth calling out: .swamp-sources.yaml persists independently of the git state of the trees it references, and those trees are frequently untracked source directories. Any git stash -u, git clean -fd, or branch switch that removes untracked files leaves the config referencing paths that no longer exist. Under df9fc306 that state is fatal to swamp version, so the CLI stops working entirely as a side effect of a routine git operation — with no edit to any swamp config, and nothing linking cause to effect.

This reinforces the suggested fix — a warning, or a check scoped to commands that actually resolve extension types. Users who hit this via stash/clean have no reason to suspect an extension source, and swamp version failing removes the first diagnostic most people reach for.

stack72 commented 7/16/2026, 8:58:51 PM

Thanks @magistr for reporting this! The fix has been merged and a release is on its way. We appreciate your contribution to swamp.

Sign in to post a ripple.