Troubleshooting

Start with fd0 doctor. It checks local chain state, vault bindings, auth wraps, orphan chain files, and the SSH agent socket.

Vault is locked

Interactive commands prompt for the passphrase when the agent is locked. Non-interactive commands fail instead of reading a secret from an unsafe input stream.

$ fd0 unlock
$ fd0 status

ssh says unknown host

Run sync. If SSH integration is enabled, sync refreshes ~/.ssh/fd0.conf. If this is the first setup on the machine, check that ~/.ssh/config includes the fd0 config.

$ fd0 sync
$ ssh -G prod-db | grep -E 'hostname|identityagent|identityfile'

Run fd0 ssh enable once if the Include line is missing. You should not need to repeat it after normal fd0 SSH changes.

SSH agent socket is stale

If ssh-add -L returns connection refused, restart fd0-agent. fd0 doctor reports this state.

$ fd0 agent restart
$ SSH_AUTH_SOCK="$(fd0 ssh sock)" ssh-add -L

kubectl or talosctl has no current context

Re-render the fd0 config. A single rendered context becomes current in the *.fd0 file. Merges preserve your existing primary config current context.

$ fd0 kube sync --merge
$ fd0 talos sync --merge

A new member cannot see a scope

The inviter must sync after adding the member. The new member then runs sync to discover and replay the scope.

# inviter
$ fd0 scope add-member bob --scope work
$ fd0 sync

# new member
$ fd0 sync