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

  • 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
  • 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)

Run all checks

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

$ swamp doctor audit
$ swamp doctor extensions
$ swamp doctor workflows

Each ends with a summary line — OVERALL: PASS or OVERALL: FAIL. If all three pass, your repository is healthy. If one fails, continue with the relevant section below.

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.

Use JSON output in CI

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

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

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

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

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

← PreviousAuthenticate with API KeysNext →CEL Expressions