Troubleshooting

Common problems and how to solve them.

No NVRs or cameras are found, or one cannot be reached

PanoPaper needs your permission to use your local network. Without it, the menu bar panel says that PanoPaper can't look for NVRs or cameras on your network, and the wallpaper and sign-in say "Local Network access is OFF for PanoPaper".

Open System Settings ▸ Privacy & Security ▸ Local Network - the panel's 'Open Privacy & Security' takes you to Privacy & Security; click Local Network there.
Turn PanoPaper on. PanoPaper notices within a few seconds and signs in by itself.

Local Network access is on and a camera still isn't found? Some cameras don't announce themselves on the network: find them with a deep scan, or add one by its RTSP URL.

The NVR or camera is on another network segment (VLAN)

PanoPaper finds NVRs and cameras by asking the network your Mac is on, and that question does not cross into other network segments (VLANs). One on another segment is added by its address instead: click 'Add…' in the menu bar panel, or + in Settings ▸ Cameras. An IP camera's address is in its own app; for an NVR, UniFi Protect keeps it under Settings ▸ Control Plane ▸ Console ▸ Network Settings; if you don't know it yet, reach that page through unifi.ui.com.

Your Mac must be allowed to reach the NVR across the segments. UniFi routes between its networks by default, but not when a network is isolated - common for a separate camera network - or when firewall rules block the way. Then PanoPaper says the NVR could not be reached. Allow your Mac's network to reach the NVR's address on two ports:

443 - signing in, the camera list and the camera pictures
7443 - the live video

An IP camera on another segment needs the same: allow your Mac to reach its address on its ONVIF port (the one in its address, often 80) and its RTSP port (usually 554, or 322 for an rtsps:// address).

The sheet says why in red; When signing in fails explains each message. Most often the account uses two-factor authentication, which PanoPaper cannot answer: make a local account on the NVR for PanoPaper - see Which account to use.

The wallpaper shows a message instead of the video

The message says what PanoPaper is waiting for - see Messages on the wallpaper. The usual fix is to sign in to the NVR again in Settings ▸ Cameras.

A camera says Offline in the menu bar panel

UniFi Protect reports it offline. Once it is back online, it becomes available within a few minutes, or as soon as you open the panel again.

Mission Control shows the normal wallpaper

That is how macOS draws Spaces in Mission Control; the video is back as soon as you pick a Space.

The desktop keys do nothing

The keys only steer the wallpaper while no window is in use. Check that:

the display under the pointer has a clear desktop and shows a camera;
the app in front has no window open on any display - clicking the desktop brings the Finder to the front, so an open Finder window keeps the keys with the Finder, even on another display;
no Spotlight, launcher or menu is open - nor the menu bar panel, where 1 to 9 choose cameras too;
the cameras are not hidden;
in the Mac App Store edition, you hold Command with the number keys, +, - and 0 (the arrows need none).

See When the keys work.

There is no audio

Audio may be muted: click the speaker in the menu bar panel's Audio box to turn it on.
You hear the camera of the main display only, on the Space you are looking at there.
Check the volume - behind windows, the audio plays at its own, lower volume - and the Output in Settings ▸ General ▸ Audio.
On a UniFi NVR, the account needs the Livestream Audio permission for that camera - the panel's Audio box then says No audio permission, and the Audio column in Settings ▸ Cameras shows a red cross (see What the account may do). The camera's microphone must also be on in UniFi Protect.

See Camera Audio.

A shortcut does nothing

If Settings ▸ Shortcuts shows "Another app uses this shortcut." under it, that app has the keys: record a different shortcut. A shortcut also does nothing while you are recording a new one.

An AirPlay display stays black

If an Apple TV used as a display stays black while the preview in the Screen Mirroring menu shows the video, AirPlay is stuck: restart the Apple TV.

"Install PanoPaper in your Applications folder?"

The Web Edition asks this when you open it from outside your Applications folder - usually straight from the Downloads folder, after unzipping the download. macOS runs a downloaded app from there in a temporary, read-only place, where it cannot update itself.

Click 'Install in Applications': PanoPaper copies itself to Applications and opens again from there. If an older PanoPaper is in Applications already, it is replaced; if your account may not change the Applications folder, macOS asks for an administrator's password. Afterwards you can delete the copy in Downloads.

Click 'Don't Install' and PanoPaper runs from where it is, and asks again the next time you open it from there.

PanoPaper Pro does not show after buying (App Store Edition)

Click 'Restore Purchases' in Settings ▸ License or in the upgrade window. PanoPaper Pro comes with the Apple Account that bought it: on this Mac, the App Store must be signed in with that account. A purchase in the Web Edition does not unlock the App Store Edition.

A license key is not accepted (Web Edition)

"There is no such license key." - check it against the one on your account page; copying the whole key is easiest.
"That license key is not for PanoPaper." - it belongs to another product.
"This license key is no longer active" - its subscription ended, or the purchase was refunded. Renew it on your account page.
"License key activation limit already reached." - it already works on three Macs: click 'Deactivate…' next to "This Mac" in Settings ▸ License on one of them, or remove one on your account page, then try again.
"This license key could not be activated." - Polar refused it for another reason; the message says why when Polar gives one.
"PanoPaper could not reach the license server." - your Mac is offline, or the connection failed. Check your internet connection, then click 'Activate' again.
"The license server could not activate your key right now." - the license server is busy or has a problem of its own; your key is not the cause. Wait a minute, then click 'Activate' again.

"Free Trial - Starts when PanoPaper can reach https://panopaper.app"

In the Web Edition, the free trial begins once PanoPaper has reached panopaper.app. Check your internet connection; if you use a firewall app such as Little Snitch, allow PanoPaper to connect to panopaper.app. The trial then starts right away, with all seven days.

PanoPaper Pro ended by itself

App Store Edition: your subscription ended, or its payment failed - renew it in the App Store ('Manage…' in Settings ▸ License), and PanoPaper Pro comes back by itself.
Web Edition: your subscription ended, or its payment failed - renew it on your account page, and PanoPaper Pro comes back by itself within a day. To have it back at once, enter your key again in Settings ▸ License.
Web Edition: your key was rotated on your account page - enter the new key. See If you rotate your license key.
Web Edition: this Mac was removed from your key, from another Mac or on your account page - enter the key again; it needs room for one more Mac.

If Settings ▸ General says "PanoPaper needs your approval in System Settings to open at login.", click 'Open Login Items Settings…' and turn PanoPaper on there.

Changing PanoPaper's language

PanoPaper comes in English, German, French, Spanish, Italian, Brazilian Portuguese, Dutch, Japanese, Traditional Chinese, Simplified Chinese, Korean, Polish, Ukrainian and Thai and uses the language your Mac is set to. To use one of them for PanoPaper alone - for example English on a Mac set to German - open System Settings ▸ General ▸ Language & Region, click + under Applications, choose PanoPaper and the language, then quit PanoPaper and open it again. The Help always appears in your Mac's language - the first of PanoPaper's languages under Preferred Languages - even when PanoPaper itself uses another.

Sending diagnostics to support

Something not working as it should? Choose 'Send Diagnostics…' in the PanoPaper menu - click ⋯ in the menu bar panel, or right-click the menu bar icon. PanoPaper puts its log and a summary of your setup into one file and opens a new email to support with the file attached. Describe what you did and what happened, and click Send.

The file contains the names of your NVRs, cameras and displays, versions and settings, and what PanoPaper did lately - you can open it before you send it. In the Web Edition it also holds the most recent reports (up to three) macOS wrote if PanoPaper quit unexpectedly in the last 30 days. It never contains passwords, license keys or email addresses. If no email account is set up in Mail, PanoPaper shows the file in the Finder: attach it to an email to thomas (at) panopaper.app.

Diagnostic messages

PanoPaper writes what it does to its log file, ~/Library/Logs/PanoPaper/PanoPaper.log, and to the system log. To read along in the system log, open Console (in Applications ▸ Utilities), click 'Start streaming', and type subsystem:com.panopaper.mac in the search field.