Troubleshoot Your Swamp Repo

This guide walks you through diagnosing a broken swamp repository using the swamp doctor suite.

Use this when

swamp update fails with permission errors or autoupdate is not working
An agent reports it cannot find swamp skills or audit hooks
swamp commands fail with extension load errors
Workflow runs fail to start or report parse errors
Model definitions contain cleartext secrets that should be in a vault
Models with sensitive outputs fail at runtime because no vault is configured
You want to verify a repo is healthy after upgrading swamp or pulling extensions

Prerequisites

swamp installed and on your PATH
A swamp repository (run swamp repo init if you don't have one) — except for swamp doctor install, which works from any directory

Run all checks

Start with all six subcommands to identify which subsystem is broken:

$ swamp doctor install
$ swamp doctor audit
$ swamp doctor extensions
$ swamp doctor workflows
$ swamp doctor secrets
$ swamp doctor vaults

Each ends with a summary line — OVERALL: PASS, OVERALL: FAIL, HEALTHY, or UNHEALTHY. If all six pass, your repository and installation are healthy. If one fails, continue with the relevant section below.

Fix installation problems

Run swamp doctor install from any directory — it does not require a swamp repository.

When the output reports UNHEALTHY, it identifies the failing check:

$ swamp doctor install
Installation Health Check

  Binary path:    /usr/local/bin/swamp
  Version:        20260518.215711.0-sha.d4a64cc1
  Binary owner:   root
  Writable:       ✗ Binary is owned by root, not current user

Autoupdate

  Enabled:        no
  Last check:     2026-05-18T22:04:59.653Z (error)
  Last error:     Cannot update /usr/local/bin/swamp: permission denied. Re-run with: sudo swamp update

UNHEALTHY

If the binary is owned by root, reinstall to a user-writable location:

$ curl -fsSL https://swamp-club.com/install.sh | sh

If autoupdate reports a permission error, run the update manually with the command shown in the output.

Fix audit integration

When swamp doctor audit reports a failure, the output includes a hint:

$ swamp doctor audit
✗ agent-config-loadable  .cursor/hooks.json is missing
    hint: Run `swamp init --tool cursor --force` to regenerate.

Follow the hint to regenerate the tool configuration. If you switched tools since initializing the repo, use --tool to check the one you actually use:

$ swamp doctor audit --tool claude

Fix broken extensions

When swamp doctor extensions reports a failure, use --verbose to identify the broken source:

$ swamp doctor extensions --verbose

The Per-Source Detail section shows each source file, its state tag, and bundle path. Look for sources in states other than Indexed — the RowState table explains each state.

To clean up stale catalog entries, preview the repair first:

$ swamp doctor extensions --repair --dry-run

If the preview looks correct, apply it:

$ swamp doctor extensions --repair

In non-interactive environments (CI), add --force to skip the confirmation prompt.

Fix workflow loading errors

When swamp doctor workflows reports a failure, the validation errors appear inline:

$ swamp doctor workflows
Checking workflows...
  ✗ broken
    → [
  {
    "expected": "string",
    "code": "invalid_type",
    "path": [
      "id"
    ],
    "message": "Invalid input: expected string, received undefined"
  }
]

0 passed, 1 failed — OVERALL: FAIL

The path field in each error points to the problem in the YAML. Fix the workflow file and re-run swamp doctor workflows to confirm.

Refer to the Workflows reference for the complete YAML schema.

Fix cleartext secrets

When swamp doctor secrets reports a failure, the output lists each definition holding a cleartext sensitive global argument and the steps to migrate it:

$ swamp doctor secrets
Scanning definitions for cleartext sensitive global arguments…

✗ 1 definition(s) hold a cleartext sensitive global argument (1 definition(s) scanned)

  leaky [@demo/secret-demo]
    • apiKey
        1. Store the secret: swamp vault put my-vault apiKey <value>
        2. Reference it:     ${{ vault.get('my-vault', 'apiKey') }}

  Each secret above sits in cleartext in its definition YAML. Migrate it to a vault, then re-save the definition.

Follow the numbered steps in the output for each finding. If no vault exists yet, create one first:

$ swamp vault create <type> <name>

Re-run swamp doctor secrets to confirm the finding is resolved.

Fix missing vaults

When swamp doctor vaults reports a failure, the output lists each definition that has sensitive resource outputs but no vault configured:

$ swamp doctor vaults
Scanning definitions for sensitive resource outputs without a vault…

✗ 1 definition(s) have sensitive resource outputs but no vault is configured (2 definition(s) scanned)
    • my-keypair [test/sensitive]

  These models will fail at runtime when writing sensitive data. Create a vault: swamp vault create <type> <name>

Create a vault for the repository:

$ swamp vault create <type> <name>

Re-run swamp doctor vaults to confirm the finding is resolved.

Use JSON output in CI

All subcommands support --json for machine-readable output:

$ swamp doctor install --json | jq '.overallStatus'
"healthy"

$ swamp doctor audit --json | jq '.overallStatus'
"pass"

$ swamp doctor extensions --json | jq '.overallStatus'
"pass"

$ swamp doctor workflows --json | jq '.overallStatus'
"pass"

$ swamp doctor secrets --json | jq '.overallStatus'
"pass"

$ swamp doctor vaults --json | jq '.overallStatus'
"pass"

Exit code 1 signals failure, so you can also use the exit code directly in CI scripts.

Doctor — complete flag, exit code, and JSON reference for all subcommands
Vaults — vault types, creation, and management
Workflows — workflow YAML schema
Extension Management — pull, update, rm commands