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

# Troubleshooting

> Solutions for common errors and issues.

If things aren't working as expected, this guide will help you diagnose and fix the problem.

## Diagnostic Commands

Before diving into specific issues, these commands are your best friends:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 1. Check current status of all sessions
sinc --list

# 2. Check the raw Mutagen sync status (detailed)
mutagen sync list

# 3. Test SSH connectivity manually
ssh user@hostname "echo connection successful"

# 4. Run sinc with verbose logging
sinc --verbose
```

## Common Issues

### 1. "Permission denied (publickey)"

**Symptoms:** `sinc` fails immediately when trying to connect.
**Cause:** The VPS is rejecting your SSH key.

**Fix:**

1. Check which key is being used: `ssh -v user@hostname`
2. Ensure your public key is in `~/.ssh/authorized_keys` on the VPS.
3. If you use a specific key, make sure it's added to your SSH agent: `ssh-add ~/.ssh/my_key`.

### 2. "Mutagen is not installed" or "Mutagen version mismatch"

**Symptoms:** Error message about missing dependency.
**Cause:** `sinc` relies on the `mutagen` binary being in your PATH.

**Fix:**
Run `sinc --setup` again to let it try installing. Or install manually:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# macOS
brew install mutagen-io/mutagen/mutagen

# Linux/Windows
# Download from https://mutagen.io/
```

### 3. Sync Conflicts ("Conflicts detected")

**Symptoms:** `mutagen sync list` shows "Conflicts". Files aren't updating.
**Cause:** A file was modified on both the local machine and the VPS at roughly the same time. Mutagen pauses to prevent data loss.

**Fix:**

1. List the conflicts: `mutagen sync list`
2. Resolve them (Mutagen usually requires manual resolution). The easiest "nuclear" option if you trust your local version:
   ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
   # WARNING: Overwrites remote changes with local version
   sinc --kill <session>
   sinc    # Restarting usually resets the sync state
   ```
   *Better resolution support is coming in future versions.*

### 4. "Session already exists"

**Symptoms:** You run `sinc` and it complains.
**Cause:** You detached from a session previously, and it's still running in the background.

**Fix:**

* **Resume it:** `sinc -r`
* **Kill it:** `sinc --kill <session-name>` (get name from `sinc --list`)

### 5. High Latency / Sluggish Sync

**Symptoms:** Changes take 5+ seconds to appear. CPU usage is high.
**Cause:** You are likely syncing `node_modules`, `.git`, or other massive directories.

**Fix:**

1. Check your ignores.
2. Run `mutagen sync list` and look at "Scanned files". If it's > 50,000, you are syncing too much.
3. Add heavy folders to `.syncignore` or the global config.

### 6. "Command not found: opencode" (on remote)

**Symptoms:** You connect, but the tmux session just shows an error or a plain shell.
**Cause:** The agent is not installed on the VPS, or not in the PATH.

**Fix:**
SSH into the VPS and install the agent globally:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
npm install -g opencode
```

Ensure `npm bin -g` is in your PATH in `.bashrc`.

### 7. File Permission Errors on Remote

**Symptoms:** "EACCES" or "Permission denied" when the agent tries to write files.
**Cause:** The folder on the VPS is owned by `root` or another user.

**Fix:**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# On VPS
sudo chown -R $USER:$USER ~/workspace
```

## Advanced Debugging

### Inspecting the Mutagen Daemon

Mutagen runs as a background daemon. If it's stuck:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
mutagen daemon stop
mutagen daemon start
```

### Inspecting the Sync Session

For a specific session, you can see detailed transfer info:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
mutagen sync list <session-name>
```

### Kill Everything

If `sinc` state gets completely desynchronized from reality:

1. Kill local process: Ctrl+C
2. Terminate all mutagen sessions: `mutagen sync terminate --all`
3. Kill remote tmux (on VPS): `tmux kill-server` (Warning: kills ALL tmux sessions)