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

# Troubleshooting & FAQ

> Symptoms, causes, and fixes for the most common Video issues

Organised by **symptom** — search for what your users report, not
what you think the cause is. Each entry links to the relevant guide
for the full context.

## The meeting page doesn't load

<AccordionGroup>
  <Accordion title="Page is served over HTTP">
    WebRTC requires HTTPS. The page embedding the meeting and the
    meeting URL itself must both be served over HTTPS. See
    [Network requirements](/guides/video/network-requirements).
  </Accordion>

  <Accordion title="Invalid or expired meeting link">
    Meeting links bind to a specific call id. If the call was
    cancelled or expired, opening the link produces an error. Issue
    a new link from the console (or the scheduling flow).
  </Accordion>

  <Accordion title="Ad blocker or privacy extension">
    Some blocklists flag third-party embedded runtimes. Ask the
    user to allowlist the meeting origin, or test with blockers
    disabled to confirm.
  </Accordion>

  <Accordion title="In-app webview (WhatsApp, Instagram, etc.)">
    Some in-app browsers strip WebRTC support or block camera
    permissions. Ask the user to open the link in the system
    browser via the app's "Open in browser" menu. See
    [Browser & device support](/guides/video/browser-device-support#in-app-webviews).
  </Accordion>
</AccordionGroup>

## Camera or microphone won't start

<AccordionGroup>
  <Accordion title="Permission was denied in a previous visit">
    Browsers cache the `denied` state indefinitely per origin. The
    user has to reset it from the browser's site-settings menu (the
    lock icon next to the URL). Pages can't programmatically
    re-prompt after a denial. See
    [Permissions](/guides/video/permissions).
  </Accordion>

  <Accordion title="Operating system has the browser blocked">
    macOS, Windows, iOS, and Android all have an OS-level camera /
    microphone toggle per app. If that toggle is off for the
    browser, no permission in the browser will help until the OS
    gate is opened.
  </Accordion>

  <Accordion title="Iframe missing `allow=camera; microphone`">
    When the meeting is embedded, the outer `<iframe>` must
    explicitly allow the features. See
    [Permissions — Embedding](/guides/video/permissions#embedding-—-iframe-allow).
  </Accordion>

  <Accordion title="Device in use by another app">
    Some native video apps — for example Zoom, Microsoft Teams,
    Google Meet, Slack huddles, Discord, and similar tools — take
    an exclusive lock on the camera or microphone and hide it
    from the browser. This applies to any app that captures
    camera / microphone, not just the ones listed. Ask the user
    to close the other app and reload.
  </Accordion>

  <Accordion title="No device connected">
    Built-in hardware disabled in BIOS, broken USB cable, or a
    webcam that lost power. Confirm the device shows up in another
    app (the OS camera app, for example).
  </Accordion>
</AccordionGroup>

## Joined but no audio / video from the other side

<AccordionGroup>
  <Accordion title="The other participant hasn't unmuted">
    Obvious but the single most common cause. Check the participant
    list — the tile shows mic / cam state.
  </Accordion>

  <Accordion title="Autoplay policy blocked audio">
    Browsers require a user gesture to play audio in some
    configurations. If the user navigated to the meeting URL
    without tapping a button first, autoplay may be suppressed —
    tapping anywhere in the meeting unblocks it.
  </Accordion>

  <Accordion title="Wrong output device selected">
    Ask the user to open meeting settings and verify the speaker
    / output device. Bluetooth headsets can appear and disappear
    without notice.
  </Accordion>

  <Accordion title="UDP blocked by the network">
    Strict firewalls can block UDP so WebRTC falls back to TCP or
    TLS. The call still connects but audio can degrade. See
    [Network requirements](/guides/video/network-requirements#corporate-firewalls-—-allowlist).
  </Accordion>
</AccordionGroup>

## Call connects but audio or video is poor

<AccordionGroup>
  <Accordion title="Weak Wi-Fi signal or congested AP">
    The most common cause of bad meetings. Ask the user to move
    closer to the access point, switch to 5 GHz, or — if on a
    busy office Wi-Fi — try tethering off a phone as an A/B test.
  </Accordion>

  <Accordion title="Competing traffic on the same link">
    Large downloads, cloud backups, or another video call on the
    same network starve real-time media of bandwidth. Pause
    heavy traffic during the meeting.
  </Accordion>

  <Accordion title="VPN tunnelling real-time media">
    Many corporate VPNs force traffic over TCP which degrades
    WebRTC. Disconnecting the VPN (when policy allows) is a
    useful A/B test.
  </Accordion>

  <Accordion title="Bluetooth headset">
    BT headsets introduce latency and artefacts that sound like
    bad network. Retry on wired earbuds or the laptop's built-in
    hardware to isolate.
  </Accordion>

  <Accordion title="Agent side hardware">
    A surprising share of "bad call" reports trace back to cheap
    USB headsets with variable mic gain. Standardise on tested
    hardware for agents.
  </Accordion>
</AccordionGroup>

## Call drops mid-meeting

<AccordionGroup>
  <Accordion title="Network switched (Wi-Fi ↔ cellular)">
    WebRTC sessions don't survive IP changes. This is a protocol
    limitation — the meeting will reconnect or drop. Ask mobile
    users to stay on one network for the duration of the call.
  </Accordion>

  <Accordion title="Packet loss spike">
    Sustained high loss causes the session to tear down. The root
    cause is network, not the meeting runtime. See
    [Network requirements](/guides/video/network-requirements#things-that-hurt-quality-predictably).
  </Accordion>

  <Accordion title="Computer went to sleep">
    Desktops sleeping typically kill the connection. Mobile
    devices locking the screen usually keep the call alive for a
    short period.
  </Accordion>

  <Accordion title="Browser tab was backgrounded for too long">
    Aggressive tab suspension on low-memory devices can kill the
    media pipeline. Keep the meeting tab in the foreground.
  </Accordion>
</AccordionGroup>

## Guest can't join — "waiting for host"

<AccordionGroup>
  <Accordion title="Host hasn't joined yet">
    The preset may enforce a wait-for-host rule. The guest stays
    in the preview until the host arrives, at which point they're
    admitted. Ask the agent to join first.
  </Accordion>

  <Accordion title="Preset denies guests when no host is present">
    Some presets are configured with "deny guest if no host". In
    that case the guest is bounced out instead of waiting. Check
    the preset used for the link.
  </Accordion>

  <Accordion title="Max wait attempts exceeded">
    Presets can cap how many times the guest retries before
    giving up. Increase the cap in the preset or pair the link
    with a scheduled slot so the host is present on time.
  </Accordion>
</AccordionGroup>

## Recording doesn't start

<AccordionGroup>
  <Accordion title="Preset doesn't have Record on start">
    Auto-record is driven by the preset's `Record on start` flag.
    See [Recording](/guides/video/recording).
  </Accordion>

  <Accordion title="Host doesn't have the recording control">
    The host preset has to expose the recording control for manual
    start / stop mid-meeting. Check the preset's control list.
  </Accordion>

  <Accordion title="Meeting ended before recording was started">
    If the meeting is short and the host never taps Start, no
    recording exists. Consider enabling `Record on start` for
    flows where recording is mandatory.
  </Accordion>
</AccordionGroup>

## Virtual background doesn't work

<AccordionGroup>
  <Accordion title="Device is too underpowered">
    Background segmentation runs locally and needs a modern GPU
    or a fast CPU. On low-end devices the background is disabled
    or becomes laggy. Ask the user to try without the virtual
    background.
  </Accordion>

  <Accordion title="Background image missing from the preset">
    The list of backgrounds is driven by the preset. If nothing
    is configured, the user sees only the built-in blur option.
  </Accordion>

  <Accordion title="Browser is out of date">
    Virtual backgrounds rely on features only present in current
    browsers. An out-of-date browser falls back to no background.
  </Accordion>
</AccordionGroup>

## Meeting link works for one person but not another

<AccordionGroup>
  <Accordion title="Different networks with different firewall rules">
    The corporate user may be on a network that blocks TURN.
    See [Network requirements](/guides/video/network-requirements).
  </Accordion>

  <Accordion title="One browser has denied camera or microphone">
    Permissions are per-browser per-origin. The user who
    previously denied needs to reset the permission.
  </Accordion>

  <Accordion title="Role mismatch">
    Host vs guest presets differ. If the link is a host link and
    the user isn't authorised, the meeting refuses to admit
    them. Check which role the link was generated for.
  </Accordion>
</AccordionGroup>

## Embedding in an iframe doesn't work

<AccordionGroup>
  <Accordion title="Missing `allow` attributes">
    The `<iframe>` must declare `allow="camera; microphone;
            autoplay; display-capture"`. See
    [Permissions — Embedding](/guides/video/permissions#embedding-—-iframe-allow).
  </Accordion>

  <Accordion title="Parent site CSP blocks the frame">
    A parent page with `frame-src` or `frame-ancestors` rules can
    prevent the meeting iframe from rendering. Review the parent
    page's Content Security Policy.
  </Accordion>

  <Accordion title="Nested iframes without delegated permissions">
    When the meeting iframe is itself nested inside another
    iframe (e.g. inside a CMS that embeds a page that embeds the
    meeting), every layer has to delegate `camera` and
    `microphone` permissions.
  </Accordion>
</AccordionGroup>

## Advanced diagnostics

<Warning>
  This section is for **technical teams** — your IT, the developer
  who embedded the meeting, or your support engineer working with
  ours. End customers will not need any of this to make a call.
</Warning>

When the symptom-based entries above don't land, the browser itself
exposes everything needed to diagnose a bad meeting. Four tools
cover almost every case.

### 1. Browser console (`F12` → **Console**)

Open DevTools on the page that shows the problem and look for
errors thrown around the moment the meeting misbehaves.

Common names to search for:

| Error                           | What it means                                                                                                  |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `NotAllowedError`               | Camera or microphone permission was denied — in the browser, the OS, or an iframe that didn't declare `allow`. |
| `NotFoundError`                 | The browser doesn't see any camera / microphone. Device unplugged, disabled in BIOS, or OS is hiding it.       |
| `NotReadableError`              | Another app is holding the device. Close the other app (see "Camera or microphone won't start" above).         |
| `OverconstrainedError`          | The requested resolution or device id isn't available on this machine.                                         |
| `Refused to frame …`            | Parent site's Content Security Policy is blocking the iframe.                                                  |
| `Permissions Policy violation`  | The outer page didn't delegate `camera` / `microphone` to the meeting iframe.                                  |
| `WebSocket connection … failed` | Signalling can't reach us — usually firewall, VPN, or a proxy breaking WebSockets.                             |

### 2. Network tab (`F12` → **Network**)

Filter by `WS` (WebSocket) and `Fetch/XHR`. Things to look at:

* The **HTTP request that loads the meeting** — status should be
  `200`. A `401` / `403` means the meeting id or auth is wrong, a
  `404` means the meeting doesn't exist or was cancelled.
* The **WebSocket connection** — should move to `101 Switching
  Protocols` and stay open. A pending or immediately-closed socket
  is usually firewall / proxy interference.
* **Blocked requests** (highlighted red with `blocked:` in the
  status). Ad blockers, privacy extensions, and corporate proxies
  sometimes block third-party origins.

### 3. Real-time stats

Chrome and Edge ship a built-in page that shows the live media
stats for every active call on the tab:

```
chrome://webrtc-internals
```

Open it in a **second tab** before the user reproduces the problem,
then read the active session. The most useful fields:

| Field                                       | What it tells you                                                                                                                         |
| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `iceConnectionState`                        | If it never leaves `checking`, the browser can't reach our media servers. `failed` / `disconnected` during a call = network interruption. |
| `packetsLost` / `packetsReceived`           | Rising `packetsLost` with a low receive rate → packet loss. This is a network problem, not the app.                                       |
| `jitter`                                    | Consistently high → unstable latency on the path (congested Wi-Fi, overloaded cellular).                                                  |
| `framesReceived` / `framesDecoded` at **0** | You aren't getting video from the other side. Check whether the other participant's camera is actually on.                                |
| `bytesReceived` at **0** for audio          | Nothing is reaching the browser at all — firewall or no media path.                                                                       |

There's a **Download PC stats** button at the top of the page —
capturing that during the bad call is the single most useful thing
for support.

Firefox has the equivalent page at:

```
about:webrtc
```

Safari doesn't expose a built-in diagnostics URL, but its Web
Inspector (enabled from the Develop menu) shows the same console
and network information as Chrome.

### 4. What to capture before escalating

When opening a support ticket for a call that failed, attaching the
following dramatically shortens resolution time:

* **App ID** and **Meeting ID / call ID**
* **Timestamp** of the problem (with timezone)
* **Browser name and version**, **OS and version**
* **Network type** — home Wi-Fi, mobile, office, VPN
* **Screenshot of the browser console** (errors, not just the
  messages area)
* **Network tab export (`.har` file)** — right-click in the Network
  tab → Save all as HAR
* **`chrome://webrtc-internals` dump** — the **Download PC stats**
  button — captured *while the call was active*, not after it
  ended
* **Steps to reproduce**

## Getting support

If none of the above matches, open a support ticket. Include the
items from **What to capture before escalating** above.

## What's next

<CardGroup cols={2}>
  <Card title="Network requirements" href="/guides/video/network-requirements">
    Ports, firewalls, bandwidth.
  </Card>

  <Card title="Browser & device support" href="/guides/video/browser-device-support">
    Supported combinations.
  </Card>

  <Card title="Permissions" href="/guides/video/permissions">
    Camera and microphone access.
  </Card>
</CardGroup>