Piik/docs/guide/troubleshooting.md

Troubleshooting

English · 简体中文 · Documentation

Find the symptom below and try the suggested checks. Stop when it works; collect a diagnostic report if the problem persists.

Common problems

What you see	Try this
Picture but no source sound	Unmute the video. The host should choose a source with shareable audio and enable sound in the source picker.
Cannot hear the host's voice	The host can enable Microphone below the picture, then check the selected input and its volume in Sharing settings → Sound. Check the device connection and microphone permission. If the control is unavailable, update the App and refresh the page.
No screen picker	Allow the browser or App to record the screen when the OS asks. Browser capture needs HTTPS or localhost; try sharing from a desktop computer.
No App windows or screens listed	Check the message in the source picker, then follow App source troubleshooting. Browser → Choose what to share opens the browser's screen, window or tab chooser.
H264 fails to start, or sharing stops just after source selection	Try Auto or VP8, then follow Windows H264 and graphics checks.
Yellow outline around the shared window or screen	This is Windows' capture indicator. See capture borders for Windows 11 controls and an optional Windows 10 workaround.
App startup fails	Read the reason on the page and in the terminal. Reopen the App and enable the chip-shaped Debug launch control after the theme button before trying again. A failed startup then exports a report; its path appears in the terminal.
Local invitation will not open	Check that both devices are on the same network and can reach each other. Guest Wi-Fi or firewall rules can block local access.
Cannot create a room (403)	On a self-hosted site, ask the administrator to check the allowed site address.
Page opens but video will not connect	Use Reconnect if available, or refresh the viewing page. See connection troubleshooting if it still fails.
WebRTC or IP-leak protection is enabled	Check whether it blocks media connections using browser WebRTC settings.
Connection fails on a campus or restricted network	Compare with a phone hotspot, then consider a site with SFU forwarding.
Sharing stops after sleep or suspension	Wake the device and return to the sharing tab; start sharing again if needed. Browser and OS suspension can interrupt capture or playback.

For a bug report, include the version, OS/browser, what you expected, and how to reproduce it. Diagnostics and export explains how to collect a local report and what to review before sharing it.

Room creation returns 403

Piik rejects room creation from a browser address that the server has not allowed, even when the page opens normally. The site administrator should:

1. Set PUBLIC_BASE_URL to the browser's site address, including the scheme and any non-default port, without a path.
2. Unset or empty ALLOWED_ORIGINS to use that address. If several addresses are needed, list every trusted origin explicitly, separated by commas. Check for an old http://localhost:8787 override after copying a configuration example.
3. Restart Piik (recreate the container with docker compose up -d for Compose), reload the page and retry.

If the response says Origin not allowed with correct settings, check that the reverse proxy preserves the browser's Origin header. A 403 from the proxy or WAF itself needs its own logs; do not disable origin validation to bypass it. See Server deployment for the configuration.

App windows or screens are missing

Keep Piik App running on the computer where you are sharing. Open the current site from the App; for a hosted site, use the App's Site mode with that site's address. If the browser asks for local-network access, allow it, then refresh the source list. If access was previously blocked, review this site's browser permissions first.

The source picker distinguishes these outcomes:

Message	Next step
Cannot connect to Piik App	Confirm the App is running and opened this site. Close unused Piik tabs using the App, then refresh the list; up to two pages can use the App's native capture or viewing at once.
Piik App and this page are incompatible	Update Piik App and reload the page.
Piik App capture is currently unavailable	Check the App diagnostics for capture or encoder availability. Review your encoding setting or use browser capture.
Could not read the screen and window list	Refresh to retry. If it keeps failing, export both the App and browser Debug reports.
No sources available	The list was read successfully, but this tab has no selectable sources. Check the other source tabs.

Local-network permission lets the page contact the App. It is separate from the WebRTC media settings described below. An unreachable App alone does not prove that permission was denied.

H264 sharing fails on Windows

If selecting a window or screen returns you to the start screen, or reports a sharing failure, it may involve capture, encoding or the Browser-to-App media connection. The message alone does not identify a graphics-driver problem.

1. Compare codecs on the same source. In Sharing settings, change the video codec from H264 to Auto or VP8, then start sharing again. If VP8 works, you can keep using it while checking the H264 path.
2. Update and restart. Update Piik App and Chrome, and install the appropriate graphics driver from your computer or GPU manufacturer's official support page. On laptops with two GPUs, check both drivers. Restart after installation.
3. For Chrome, check graphics acceleration and GPU preference. In Chrome's Settings → System, enable graphics acceleration if it was disabled, then restart Chrome (Google's setting instructions). On a multi-GPU Windows PC, open Settings → System → Display → Graphics, select or add Chrome (chrome.exe), and choose Options → High performance → Save. Completely quit and reopen Chrome before retrying. If it does not help, restore Let Windows decide (Microsoft's graphics settings).

The Windows preference is a browser-side check, not a guarantee of H264 support. Piik App selects its native encoder separately; changing Chrome's GPU preference does not select the App's capture GPU. If App capture still fails, keep the codec comparison and export the App and browser reports for the same attempt. Include your GPU model, driver version, source type and whether VP8 works. If both codecs fail, also check WebRTC restrictions.

Yellow capture border on Windows

Windows draws this outline to identify the window or display being captured. On supported Windows versions, the App source picker offers Show capture border, off by default. Windows permissions or another active capture can still require the border. Windows 10 does not provide this control for its capture API.

Windows 11: the border is still visible

1. Select Apps / Windows or Screens in Piik and leave Show capture border off. A Browser-selected source uses the browser's own capture indicator.
2. Stop other apps or tabs capturing the same window/display, then restart sharing.
3. If Windows denied borderless capture, review Screenshot borders in Windows privacy settings. Its settings page can also be opened with ms-settings:privacy-graphicscapturewithoutborder from Win+R, when available.

Windows requires consent and can retain the border when another capture requests it (Microsoft's API documentation). If it persists, include the Windows version, selected source type and an App diagnostic report with your feedback.

Optional Windows 10 workaround

DWM Custom Projection Border is a third-party Windhawk mod for x64 Windows that can hide the border while keeping the same capture method. It changes Windows' desktop compositor and affects other apps' capture indicators too. The author shows it working on Windows 10 21H2; this procedure has not been tested with Piik on a Windows 10 device.

1. Install Windhawk from its official website.
2. In Windhawk's global Settings → Advanced settings → More advanced settings, append dwm.exe to Process inclusion list and save. Keep existing entries.
3. Find and install DWM Custom Projection Border. In the mod's settings, turn on Disable border and save.
4. Stop and restart sharing in Piik, then check whether the border disappears.

To undo this, disable the mod and restart sharing. Remove the dwm.exe entry if you added it only for this mod. If desktop problems appear or a Windows update breaks compatibility, disable the mod first.

See the mod author's instructions and Windhawk's process settings for current setup details.

When video will not connect

No media route available means Piik has not found a working path to deliver the picture to your device. Loading the page and receiving media use different connections, so one can work while the other fails.

NAT (Network Address Translation) lets several devices share an Internet address. Routers and providers differ in how they map addresses and admit incoming traffic; some combinations make direct connections difficult. Firewalls and browser policies can also block media. The message alone does not identify the cause.

Try these in order, stopping when the picture arrives:

1. Retry the viewing page. Choose Reconnect if it is available. If it is disabled or does not help, refresh the viewing page or reopen the invitation. Let each connection attempt finish. One or two fresh attempts can be worth trying; repeated refreshes cannot remove a network restriction.
2. Check browser WebRTC settings. Browser settings or VPN/privacy extensions can block media even while the page loads. This affects both sharing and viewing; follow browser WebRTC checks below.
3. Try another network. For example, test a phone hotspot. If you use a VPN or proxy, check its UDP policy; ask the administrator on a managed network.
4. Enable usable IPv6. Check that your provider, router and device support it. When both peers have working IPv6, Piik can try that direct path alongside IPv4. It does not bypass firewall rules; keep IPv4 enabled too.
5. Check your own router, if you manage it. On a trusted home network, supported UPnP, PCP or NAT-PMP settings can let the App's native media path request a port mapping. Browser-only capture does not request these mappings. If a modem and router both perform NAT, follow your model's bridge/AP-mode instructions to remove the extra layer. Carrier-grade NAT is upstream of your router; ask your provider about available public IPv4 or IPv6 service. Back up settings before changing the router's operating mode.
6. Invite a friend on another network. A Viewer who can receive the picture and has spare forwarding capacity may give Piik another path to you. Piik chooses this automatically; extra people help only when those connections work.
7. Use a site with media fallback. Its operator must enable SFU forwarding. If the site offers Privacy mode, the Host must turn it off before sharing. Sites configured for Server media already require SFU. The public demo.piik.tv site and the App's Public invite mode do not provide SFU. Self-hosting is an advanced option. Both P2P and SFU media currently use UDP; a network that blocks UDP entirely still needs a different network or an administrator's help.

Router menus vary by model. These manufacturer guides explain IPv6 prerequisites, UPnP, and double NAT with a modem and router. The WebRTC connection guide explains discovery and connection checks in more technical detail.

If these steps do not help, collect a Debug report from the affected Viewer and, if possible, the Host for the same attempt. Include the time, Piik version and network type when reporting the problem.

Browser WebRTC restrictions

WebRTC carries Piik's picture and sound. Disabling it or blocking non-proxied UDP can prevent viewing and even the local Browser-to-App media connection. Successful source selection does not prove that connection works. Hiding local IP addresses alone does not necessarily block WebRTC.

1. Open the same invitation in a browser profile with default settings and no VPN/privacy extensions. If that works, check the original profile's WebRTC or IP-leak protection settings.
2. Restore a policy that allows WebRTC UDP. A policy named disable_non_proxied_udp is restrictive; the browser default is a useful comparison. Vivaldi exposes Settings → Privacy and Security → WebRTC IP Handling → Broadcast IP for Best WebRTC Performance. Chrome extensions can control this policy even without a visible browser switch.
3. Reload the affected Piik page and retry. If a school or company manages the setting, ask its administrator to review it.

Allowing these connections can expose network addresses to WebRTC peers; change only the relevant setting. See Chrome's policy reference and Vivaldi's privacy settings.

Campus networks and strict NAT

A campus network can work with Piik, but a shared Internet gateway or restrictive firewall may make direct connections harder. Try a phone hotspot first: if the same invitation works there, focus on the original network's restrictions.

For regular use, consider self-hosting a Piik site with SFU media forwarding. This gives viewers a server path when direct connections fail. Follow the deployment guide, including its public-address and UDP-port requirements. The Host can then open that site through the App's Site mode and send invitations from the new site.

The public demo and App Public invite mode remain P2P-only. SFU also requires usable UDP: when the network blocks UDP entirely, use another network or ask the administrator for access. Deploying a server alone does not remove that restriction.

Ready to host a site for your group? Follow self-hosting. For other guides, return to the documentation home.