swamp-troubleshooting

Start by reading stderr and re-running the command with --json to see structured error details and exit codes. If the failure maps to a known integration, run the matching swamp doctor command first, since it names the failing piece directly.

Run swamp doctor extensions, which forces a catalog rescan and reports per-registry failures for models, vaults, drivers, datastores, and reports. Use --json for CI gating and --verbose for per-source detail.

Run swamp doctor extensions --json to identify load failures, then check stderr for swamp-warning: lines such as missing CalVer version fields. Verify deno check passes and confirm the file sits in the auto-discovered extensions/models directory.

Set OTEL_EXPORTER_OTLP_ENDPOINT to a collector such as local Jaeger and re-run the workflow. Inspect the span waterfall to find the longest swamp.workflow.step spans and drill into model method and driver execute spans.

Fetch source with swamp source fetch only when doctor commands, error inspection, and tracing fail to explain the behavior, or when the question is about internal implementation. Source reading is the most expensive diagnostic tier.

Use --skip-check <name> to skip one check or --skip-checks to skip all when running a method. Checks listed as required in the model definition's checks.require cannot be skipped via CLI flags and must be edited in the YAML definition.