# First-run troubleshooting

Use this page for the most common first-run failures: **you cannot see synced clips**, **only one direction works**, or **history shows a clip but paste fails**. Follow the flow in order to reduce guesswork.

If you are still on **one device** checking clip history and have not tried cross-device yet, start with [Copy & paste](/getting-started/first-steps). This page assumes you are already validating **between two devices**.

When a cross-device clip “never shows up,” first check the **source device’s clip history** for that copy: **if it never appears there, suspect recording/capture before you assume “sync is broken.”** Mobile OS rules around foreground/background reads matter; desktop cases are covered in the **platform tabs** below. For a shorter primer, read [Recording expectations](/getting-started/clipboard-record-expectations); **if you are actively failing, start troubleshooting from the sections below**.

## Who this is for

- You finished onboarding cross-device or sync checks, but the outcome is wrong
- You are unsure whether to start with network/sync setup or single-device permissions/background

## Identify your symptom first

| Symptom | Check first |
|---|---|
| Devices cannot see each other’s new clips | Same sync method on both sides, online state, network blocking; on **Android/iOS** use the matching **tab below** for “never wrote history”; on **desktop** start with network/app running state, then **macOS** [permissions](/advanced/macos/permissions) if relevant |
| Only one direction fails | Permissions and background state on failing source device |
| History has records but paste fails | Target app paste behavior and system paste restrictions |
| Sync delay is obvious | Network quality, background limits, power-saving mode |

> [!WARNING] Do not mix sync paths
> If one device uses Nearby Sync and the other uses Cloud Sync, you often see “nothing shows up” or highly unstable results. Align both sides first, then run **Ordered checks** below.

## By platform: background monitoring vs “sync looks broken”

When a new clip does not show up cross-device, first confirm whether the **source device actually wrote that copy to clip history**. If history never gets an entry, the other side has nothing to sync—this is not always “wrong sync mode”. Pick your platform tab below. For full detail, see [Clipboard background monitoring](/features/source/background-monitoring/).

:::tabs
:::tab{label="Desktop (Windows / macOS)"}

With a normal install, clipboard background capture is usually **on by default**, so first-run troubleshooting **rarely** hinges on “must open the app’s main window before copies land in history.” If the source is desktop but it still feels unsynced, keep following the ordered checks for sync method, network, and online state.

On **macOS**, if auto-paste, Input Monitoring, or privacy prompts are involved, also check [macOS permissions](/advanced/macos/permissions) and [Platform differences](/advanced/platform-differences). For the full model, read [Clipboard background monitoring](/features/source/background-monitoring/).

:::
:::tab{label="Android"}

When **clipboard background monitoring** is **not available** (disabled, not fully set up, or blocked by notification/battery policies), new copies often only become reliable if you **open the app** and copy again so history fills—then sync can catch up. That can feel like “sync is broken” when the source never recorded the clip.

Read [Clipboard background monitoring](/features/source/background-monitoring/) for the model; use [Quick start](/features/source/background-monitoring/quick-start) when you need toggles. For a shorter read on the same situation, see [Recording expectations](/getting-started/clipboard-record-expectations).

:::
:::tab{label="iOS"}

iOS does **not** support the same **continuous background clipboard monitoring** as desktop/Android. The practical alternative is to **manually** hand off the clipboard via **Shortcuts** or the **system Share sheet**, often **without** opening the main app UI first (system share UI may still appear—follow what you see on device). Returning to the app remains a common path too.

See [Clipboard background monitoring](/features/source/background-monitoring/), [iOS overview](/advanced/ios/), and [Platform differences](/advanced/platform-differences).

:::
:::

## Ordered checks

:::steps
:::step{title="Confirm both devices are running"}

Make sure the app opens on both sides and clip history is accessible.

:::
:::step{title="Confirm same sync method on both devices"}

Use Nearby Sync on both devices, or Cloud Sync on both devices. Do not mix paths.

:::
:::step{title="Run a minimal text test"}

Copy on device A:

```text title="Minimal test text" noLineNumbers
octoclip-troubleshooting-001
```

Then check if the same text appears in device B history.

:::
:::step{title="Rule out network and OS interception"}

Temporarily disable VPN/proxy for retest, and check whether OS applies background or power restrictions.

:::
:::step{title="Run reverse-direction test"}

Copy a new text on device B and check device A. Confirm whether issue is one-way or two-way.
:::
:::

## Common fixes

If the ordered checks already narrowed the area, open the matching item below for **extra actions** (these complement the steps above; they do not replace them).

:::accordion{multiple}
:::item{label="No new clip appears on target device"}
- Keep sync method identical on both devices.  
- Verify both apps are active and online.  
- Test plain text first, then complex content.  
- **Windows / macOS**: “background monitoring off” is uncommon; check whether the app quit, firewall/security software, and **macOS** [permissions](/advanced/macos/permissions).  
- **Android**: if background monitoring is off or ineffective, retest after **opening the app**, or configure via [Quick start](/features/source/background-monitoring/quick-start).  
- **iOS**: try **Share sheet** or **Shortcuts** to hand off the clip; see [iOS overview](/advanced/ios/).

:::
:::item{label="Only one direction fails"}
- Focus on permissions and background state of the source device in failing direction.  
- Reopen app on source device and retest.  
- If still failing, restart source device and test again.

:::
:::item{label="History has item but paste fails"}
- Test with a basic text input field first.  
- Check system-level paste restrictions.  
- Re-copy and paste immediately to rule out stale state.
:::
:::

## Validate after fix

- Copy `octoclip-troubleshooting-001` on device A.
- Confirm it appears in device B history.
- Paste successfully on device B.
- Reverse direction also succeeds (device B -> device A).

## Next steps

:::cards{cols=2}
:::card{title="Copy & paste" icon="lucide.play" href="/getting-started/first-steps"}
If you suspect one device never writes history, rerun the shortest local check.

:::
:::card{title="Cross-device" icon="lucide.copy" href="/getting-started/first-cross-device-paste"}
Return to the first cross-device page and repeat the shortest end-to-end check.

:::
:::card{title="Clipboard background monitoring (platform topic)" icon="lucide.monitor-cog" href="/features/source/background-monitoring/"}
Understand “nothing records until I open the app” vs sync issues.

:::
:::card{title="Sync overview" icon="lucide.git-compare" href="/features/sync-overview"}
If things stay unstable, confirm the sync method fits your scenario.

:::
:::card{title="FAQ" icon="lucide.circle-help" href="/getting-started/faq"}
Daily questions about shortcuts, resource usage, and more.
:::
:::

## Still stuck

Please include:

- Platform and OS version on both devices
- App version on both devices
- Sync method (Nearby Sync / Cloud Sync)
- Network context (same Wi-Fi / different networks / VPN / proxy / firewall / corporate network)
- Failure direction (A -> B / B -> A / both directions)
- Content type (plain text / image / link / files / other)
- **Windows / macOS**: whether the app stays running; firewall/security tools; **macOS** whether you checked [permissions](/advanced/macos/permissions)
- **Android**: whether clipboard background monitoring is configured; whether “open app then copy” changes behavior
- **iOS**: whether you used Share / Shortcuts as an alternative path
- Minimal reproduction steps
- Expected result and actual result