Troubleshooting

Authentication Issues

Session expired

This error occurs when your access token has expired and the refresh token is no longer valid. This typically happens if you have not used the CLI for an extended period, or if the refresh token was manually revoked.

Solution: Log in again to obtain new tokens.

Not logged in

This error means no authentication tokens are present in your config file. You either have not logged in yet, or your config file was deleted or corrupted.

Solution: Run the login command to authenticate.

Device Issues

No device registered

You are logged in but have not added the current machine as a device. Each device must be registered before it can sync.

Solution: Register the current device.

Device not showing in list

If a device does not appear in your device list, it may be inactive or was removed from another machine. Devices that have not synced in over 90 days are automatically marked as inactive but remain in the database. Check the lastSeenAt timestamp when listing devices to see when each device last contacted the API.

Sync Issues

Request timed out

This error indicates that the CLI could not connect to the API server within the timeout period. The server may be down, unreachable, or experiencing high latency.

Solution: Check your internet connection and verify that the API URL in your config file is correct.

{
  "apiUrl": "https://api.claude-sync.com",
  ...
}

Sync shows 0 files

If sync reports that there are no files to upload, it means the CLI did not find any Claude Code session data in the current project directory. This happens when you have not yet used Claude Code in the project, or if the ~/.claude/projects/ directory does not exist.

Solution: Use Claude Code to create some sessions, todos, or artifacts, then run sync again. The CLI scans ~/.claude/projects/{encoded-project-path}/ for session data.

Files missing after pull

If files are not appearing after a pull, verify that the symlink was created correctly. The CLI creates a symlink at ~/.claude/projects/{foreign-encoded-path}/ pointing to the downloaded data. Also check that you selected the correct source device when pulling.

Solution: Run claude-sync status to see the current project state and linked foreign directories. Try pulling again with the --verbose flag to see detailed output.

Path Issues

Symlink errors on Windows

Windows requires administrator privileges or Developer Mode to be enabled for creating symlinks. If you encounter permission errors when pulling sessions, you need to enable Developer Mode in Windows Settings.

Solution: Go to Settings → Update & Security → For developers, and enable Developer Mode. Alternatively, run the CLI as an administrator.

Wrong project directory

If sync is operating on the wrong project, the encoded path may be incorrect. The CLI derives the encoded directory name from the current working directory, so running sync from a different location will result in a different encoded path.

Solution: Check the current project path with claude-sync status. Ensure you are running sync from the correct project root directory. The encoded path replaces / and . with -.

Getting Help

If you encounter an issue not covered in this guide, please reach out to our support team. Include the output of claude-sync status and claude-sync whoami along with any error messages you received.