> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gethandshake.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Correct common service, port, agent connection, and session synchronization problems.

## The health check fails

1. Run `handshake serve` in a terminal.
2. Read the error message.
3. If the port is in use, run `handshake setup`.
4. Run the health check again.

```bash theme={null}
curl http://localhost:8765/health
```

Use the configured port if it is not `8765`.

## An agent cannot connect

Run:

```bash theme={null}
handshake setup
```

This command writes the current MCP URL to each detected agent. Restart the
agent after setup completes.

Make sure that `HANDSHAKE_ADDR` and `HANDSHAKE_URL` use the same port.

## A session is not in the list

Import native sessions:

```bash theme={null}
handshake pull
```

You can limit the import to one agent:

```bash theme={null}
handshake pull codex
```

Then list the sessions again.

## The list contains a synchronization warning

The warning identifies the agent storage that Handshake could not read. Check
that the storage exists and that your account can read it. A partial import
does not remove sessions that Handshake imported successfully.

## Claude Code hooks do not run

Make sure that Python 3 is on `PATH`. Then run:

```bash theme={null}
handshake setup
```

Handshake can still use MCP tools when the automatic hooks are not available.

## Project knowledge remains stale

Check the writer:

```bash theme={null}
handshake knowledge author show
handshake knowledge author test
```

If no writer is selected, configure one:

```bash theme={null}
handshake knowledge author setup
```