# Troubleshoot Guv setup

> Correct the first failed `guv status` line. Then diagnose the first App Job.

## Get help from a coding agent

If setup installed the Guv support skill, ask that coding agent to help you debug. The skill tells the agent to use Guv CLI commands and protect credentials.

You can also use the status instructions below.

## Status lines

- `config MISSING`, `api MISSING`, `api INVALID api_url`, `auth MISSING`, or `auth INVALID guv_token`: Run `guv setup`, then approve the displayed code in Familiar App.
- `config INVALID`: Stop Guv and contact Guv support. `guv setup` does not overwrite malformed configuration.
- `api UNREACHABLE`: Examine the network and [Familiar API health](https://api.familiarlabs.org/health).
- `auth FAILED`: Run `guv setup` and approve a new Device Authorization in Familiar App.
- `handler NOT RUNNING`: Make sure that the selected coding-agent command exists and its login is active. For Claude Code, also examine its configured working directory and settings.
- `handler INVALID`: Use `guv setup` to select and configure a Handler again.
- `daemon not running`: Use `brew services restart guv`. For a direct archive, start `guv run`.
- `skipped until …`: Correct the earlier failed line first.

- `401 during setup`: a Device Authorization expires ten minutes after `guv setup` shows it. Run `guv setup` again and approve the new code.

## Connect a computer

`guv setup` shows a code. Enter that code in Familiar App, then approve the computer.

If the App does not show the computer, enter the same code again. A repeated code is not a wrong try.

Familiar accepts five wrong codes in ten minutes. After five, the App shows “Too many incorrect computer codes.” Wait ten minutes, then enter the code again.

The code expires ten minutes after `guv setup` shows it. Run `guv setup` again to get a new code.

## New or restored phone

Familiar keeps the App credential on one device. It is not in your iCloud backup, and it does not transfer to a new phone.

Ask for a new setup email. Install Familiar, then paste the one-time code on the **Paste your setup code** welcome screen.

If the new phone restored your Familiar data, that code returns you to the same setup. Guv stays connected and your Jobs stay. Do not run `guv setup` again.

Notifications start again after you open the App.

If Familiar already runs and shows **Familiar needs re-pairing**, a newer setup code replaced this credential. Open **Settings**, then paste a new code in **Reconnect Familiar**.

## First Job

`Working` means that the Job status is `running`.

A notification does not prove successful Job completion.

Setup is complete only when the App shows `Done` and displays the requested Outcome.

### The App reports Handler failed while `guv status` shows handler ok

`handler ok` shows that the selected Handler Process is ready. It does not show that the selected coding agent can answer.

Do a direct check of the selected coding agent. Do not examine Homebrew or `launchd` first. Do not restart Guv repeatedly.

For Claude Code, use this command from the configured working directory:

```sh
claude -p 'Reply with exactly: agent works' --output-format json
```

For Pi, use this command:

```sh
pi -p --no-session --no-tools 'Reply with exactly: agent works'
```

If the coding agent reports an account error, use its official documentation. If the model account caused the error, use the model-provider documentation.

Report only safe actions that the user can do. Do not paste raw output, credentials, session identifiers, or private paths.

If the direct test succeeds, examine the Handler diagnostics. Then examine the daemon log.

For Homebrew or Linuxbrew, use these commands:

```sh
CLAUDE_HANDLER="$(brew --prefix)/bin/guv-handler-claude"
"$CLAUDE_HANDLER" logs
guv logs
```

For a direct archive, use these commands:

```sh
"$HOME/.local/bin/guv-handler-claude" logs
guv logs
```

`guv logs` follows the daemon log and can contain old entries. Use entries from the current restart or Job.

The log does not contain raw coding-agent errors or Job content.

## Push

Use `guv doctor` to diagnose push or notification delivery.

If it reports missing push registration, open Familiar App and wait for “Push ready.” The App registers again each time you open it. Then try again.

## Homebrew service

```sh
brew services restart guv
guv status
```

Use `guv logs` only when the current status or Job identifies a daemon problem.

## Direct archive

A direct archive has no Homebrew service. Examine the foreground `guv run` terminal or process supervisor. Then restart that process.

## Incompatible pre-release database

Stop Guv and contact Guv support. Do not remove the user's working directory.