Troubleshooting

• Verify Tailscale is up on both client and host.
• Check the target with yeet list-hosts.
• Override host: CATCH_HOST=<host> yeet status.
• See Tailscale for tailnet setup details.

• yeet run will fail if the binary arch does not match the host.
• Build with GOOS=linux GOARCH=<arch>.

• Docker compose services require docker on the host.
• catch install can prompt to install docker if missing.
• If a netns-backed compose service becomes unreachable after networking changes, catch will now reconcile that service at startup by recreating the compose project when it detects stale docker endpoint wiring for the current service netns. Check the catch logs for a message saying it recreated the service during netns reconciliation.
• For published compose ports inside svc, yeet now owns the service-netns DNAT chains directly. If you suspect stale port forwarding, inspect the service netns and expect to see YEET_PREROUTING and YEET_OUTPUT as the active chains rather than old direct OUTPUT ... DNAT rules.
• If you need to force the same repair manually, restart the service through yeet or restart the service's yeet-<svc>-ns.service unit and let catch reconcile it on the next start.

• New Debian and Ubuntu hosts should prefer native nft.
• iptables-nft is the compatibility path.
• iptables-legacy should only appear as a fallback compatibility mode.
• Check that the yeet-owned firewall objects exist:

sudo nft list table ip yeet
sudo iptables-nft -S YEET_FORWARD
sudo iptables-nft -t nat -S YEET_POSTROUTING

• On legacy hosts, replace iptables-nft with iptables-legacy.
• Verify forwarding is enabled on the host:

sysctl net.ipv4.ip_forward

• If the yeet namespace service needs to rebuild networking state, restart it:

sudo systemctl restart yeet-ns.service

• catch now runs host-level netns reconciliation in the background, so yeet status should return promptly after catch restarts. If catch shutdown or restart appears hung, inspect journalctl -u catch for the underlying docker or netns command that failed to exit.

• yeet edit needs a TTY to launch $EDITOR.
• Run from a real shell, not a non-interactive session.

• Use stage show to inspect, then stage clear to discard staged changes.

• One side must be a remote svc: or svc:path.
• Remote paths are relative to the service data dir (data/).
• yeet copy defaults to rsync-like -avz behavior (archive/recursive, verbose, compress).
• Use a trailing slash on the source to copy directory contents (rsync-style).
• Absolute paths are rejected.

• Use --format=json or --format=json-pretty if the table is not useful.

• A service's type is fixed after first install.
• If you installed as docker compose, you cannot later install a binary with the same name.