Skip to main content

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
  • swamp doctor datastores reports foreign namespace contamination in a giga-swamp repository
  • Workflow runs or suspended approvals are missing after a namespace contamination incident
  • 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 seven subcommands to identify which subsystem is broken:

$ swamp doctor install
$ swamp doctor audit
$ swamp doctor datastores
$ 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 seven 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 datastore health and namespace contamination

This section applies to custom (remote) datastores with a namespace configured. Filesystem datastores do not have this problem — if swamp doctor datastores passes on a filesystem backend, no action is needed.

For background on what namespace contamination is and why it happens, see Datastore Architecture.

Run the health check:

$ swamp doctor datastores

If the output reports contamination, preview what the repair will clean up:

$ swamp doctor datastores --repair

The preview lists the foreign namespaces found, their object counts, and the five cleanup steps that will run. Review the foreign namespace list to confirm these are not objects you need to keep.

If the preview looks correct, execute the repair:

$ swamp doctor datastores --repair -y

The repair runs five steps in sequence: delete foreign objects, rebuild the remote index, wipe the local cache, re-pull scoped data, and invalidate workflow run and catalog indexes. On completion, it reports how many workflow runs were recovered.

If the repair fails mid-way, the error output identifies which step failed and provides a restore command. Run the suggested command to restore local state:

$ swamp datastore sync --pull

Then re-run swamp doctor datastores to reassess and retry the repair.

After a successful repair, verify that previously missing workflow runs are now visible:

$ swamp workflow runs

Suspended approval runs that were unreachable should also reappear:

$ swamp workflow approvals

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 --yes 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 datastores --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.

Authentication errors

If you see an authentication error when running any of the commands below, authenticate first:

  • swamp datastore setup extension
  • swamp vault create (with a non-local type)
  • swamp serve --auth-mode token|oauth
swamp auth login

If you are using a collective token (swamp_org_ prefix) and see a scope error, the token is missing the required scope. Create a new token with the appropriate scope (datastore:*, vault:*, or serve:*) in the collective's settings page:

swamp auth whoami

Check the Scopes line to confirm which scopes the token carries. Refer to the API Key Authentication reference for the full scope table.

  • 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
← PreviousAuthenticate with API KeysNext →Gate a Workflow with Manual Approval