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.

Account and sign-in errors

Every command except a few exempt ones needs a swamp-club.com account. See Swamp Account Requirement for which commands are exempt and how verification works.

When Swamp blocks a command, --json output reports why as data, and the exit code says whether retrying can help:

{
  "error": "Could not reach swamp-club.com to verify your identity.\n\n  ...",
  "code": "auth_gate_blocked",
  "reason": {
    "kind": "unreachable_unverified"
  },
  "temporary": true
}
  • Exit code 75 — a temporary block (refused, unreachable_unverified, unverified_for_a_day). A later run can succeed without changes, so CI can retry.
  • Exit code 1 — a block that needs you to act (no_credential, revoked).

swamp auth whoami runs without verification, so use it to see what swamp-club.com returns for your credential.

No account

swamp requires a swamp-club.com account to run.

  Run `swamp auth login` to create an account or sign in.
  It takes about 30 seconds.

  In CI, set SWAMP_API_KEY and SWAMP_SIGNIN_TOKEN from a collective
  token created at swamp-club.com/collectives.

  For a serve or worker daemon, sign in as the user that enabled it
  and re-run `swamp serve daemon enable` or `swamp worker daemon enable`.

Swamp found no credential. Fix it for where the command runs:

  • On your machine: run swamp auth login.
  • In CI or a container: set SWAMP_API_KEY and SWAMP_SIGNIN_TOKEN from a collective token. swamp-club.com/collectives redirects to your collectives list; open the collective's Settings page to create one. See Run Swamp in CI.
  • In a daemon: run swamp auth login as the user who enabled the daemon, then run swamp serve daemon enable or swamp worker daemon enable again. A worker daemon enabled before the account requirement must be re-enabled.

A swamp worker connect without a credential does not stop here. It waits for its orchestrator's pass, and a refusal reads as below.

Worker not vouched for by its orchestrator

Worker stopped: auth gate blocked

Error: swamp requires a swamp-club.com account to run.

  This worker has no credential of its own, and the orchestrator it
  enrolled with did not vouch for it: the orchestrator sent no pass.

  The orchestrator's swamp may predate worker gate passes: upgrade it.
  Or give the worker a credential (SWAMP_API_KEY_FILE). See
  https://swamp-club.com/manual/reference/swamp-account-requirement

A worker with no swamp-club.com key passes through the orchestrator that enrolls it, and this one did not. The worker exits with code 1 and takes no work. Fix it by the reason after did not vouch for it::

  • the orchestrator sent no pass: upgrade the orchestrator to v20261008.183339.0-sha.231eda34 or later. An older one has already redeemed the enrollment token, so create a new one if it allows no more enrollments.
  • the orchestrator has no signed pass to give: the orchestrator started offline, on a signin token alone, or while swamp-club.com returned errors. Restart it while it can reach swamp-club.com.
  • the orchestrator's pass had expired: the orchestrator could not renew its proof. Check that it can reach swamp-club.com, or restart it.
  • the orchestrator's pass is malformed, or ... is not signed by a swamp-club key this worker trusts: run swamp update on the worker and the orchestrator so both trust the same swamp-club.com keys.

For any of these, giving the worker its own credential also works: set SWAMP_API_KEY and SWAMP_SIGNIN_TOKEN from a collective token. A worker on Windows or on Alpine and other musl-based Linux needs one, because its steps cannot pass on the orchestrator's pass there. See Remote workers.

Credentials revoked

Your swamp-club.com credentials have been revoked.

  This can happen if your API key was deleted or your account was
  suspended.

  Run `swamp auth login` to sign in again.

swamp-club.com no longer recognizes the key. Run swamp auth login. For a collective token, create a new token, and replace both SWAMP_API_KEY and SWAMP_SIGNIN_TOKEN wherever they are set.

Could not reach swamp-club.com

Could not reach swamp-club.com to verify your identity.

  swamp verifies your credentials once before it can run offline.
  Check your network connection and try again. `swamp auth whoami`
  works without verification and shows what swamp-club.com returns.

Swamp holds no valid verification and could not reach swamp-club.com. Check the network, then run the command again. In CI, set SWAMP_SIGNIN_TOKEN beside SWAMP_API_KEY so jobs keep running when swamp-club.com is unreachable.

If the verification has expired, the message instead reads:

Your identity hasn't been verified in 15 days.

  swamp needs to check in with swamp-club.com periodically.
  Check your network connection and try again. `swamp auth whoami`
  works without verification and shows what swamp-club.com returns.

Connect to a network that can reach swamp-club.com and run any command.

Check refused

Could not verify your identity: swamp-club.com, or a proxy between
you and it, refused the check (HTTP 429).

  Retry in 45s. If you are behind a corporate proxy, check that it allows
  swamp-club.com. Once verified, swamp keeps working through
  swamp-club outages.

swamp-club.com rate-limited the check, or a proxy or firewall answered in its place. The HTTP status and wait time vary. Wait and retry. Behind a corporate proxy, ask for swamp-club.com to be allowed. In CI, a SWAMP_SIGNIN_TOKEN lets jobs run without this check.

swamp-club.com failing for over 24 hours

Could not verify your identity: swamp-club.com has been failing for
over 24 hours.

  swamp runs unverified for at most a day. Please try again later.

swamp-club.com has returned server errors since your first unverified run more than a day ago. Try again later. Once any check succeeds, Swamp runs normally.

Warnings while offline

These warnings print to stderr and the command still runs:

  • Running offline (could not reach swamp-club.com); using your cached verification. — Swamp holds a valid verification, so it runs without swamp-club.com.
  • Running unverified for up to 24 hours: swamp-club.com is returning errors. swamp will block once it has been unable to verify you for a day. — swamp-club.com is failing and Swamp has no verification yet. Once the 24 hours pass, the command is blocked.

Both key variables set

Error: SWAMP_API_KEY and SWAMP_API_KEY_FILE are mutually exclusive — unset one of them

Unset one of the two variables.

Scope errors with a collective token

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