advanced-camera-card/docs/troubleshooting.md

Troubleshooting

Highlighted Issues

Legacy dashboard resource detected

You still have the old frigate-hass-card.js resource registered in your dashboard (and not advanced-camera-card.js). Having both registered causes duplicate element registration errors and unpredictable behavior. Symptoms include the card not loading, the version changing between reloads, or log entries like:

Failed to execute 'define' on 'CustomElementRegistry': the name "focus-trap" has already been used with this registry window

To fix:

1. Edit your dashboard (click the three-dot menu in the top right) and select Manage Resources.
2. Remove any entry referring to frigate-hass-card. You should only have a single entry for advanced-camera-card.
3. Optionally, delete the frigate-hass-card directory on your filesystem if present (e.g. $HA_PATH/www/community/frigate-hass-card), as long as an advanced-camera-card directory exists there too.
4. Clear your browser cache and reload.

If you are an admin user and the card detects both resources are registered, an alert icon will appear in the status bar -- clicking it will display a notification with a button to automatically remove the legacy resource.

Configuration upgrade available

If you see a notification that a configuration upgrade is available, it means your card configuration uses an older format that can be automatically updated.

To upgrade:

1. Open your Home Assistant dashboard.
2. Click the pencil icon to enter edit mode.
3. Click the three-dot menu on your card and choose Edit.
4. In the card editor, click the Automatic Upgrade button at the top.
5. Review the changes and save.

If the automatic upgrade button is not visible, your configuration may already be up to date. Try clearing your browser cache and reloading.

Media does not load

Media not loading? Permanent "loading circle"?

Media failing to load is a relatively common error, but can be caused by any number of issues (e.g. installation problems, networking problems, video/codec problems, a Home Assistant bug or card bug). This applies to live streams, recorded media in the viewer, and image views.

During a live stream load, the card will show a "loading circle" icon and, for cameras with a camera_entity configured, will show images refreshing once per second until the stream has fully loaded (unless live.show_image_during_load is set to false).

Debugging steps:

1. If you're using the default auto live provider, or explicitly setting the ha live provider, try opening the camera_entity in Home Assistant and verifying whether the stream loads there. You can press the e key on any Home Assistant dashboard, choose the relevant entity, and see if the stream loads. If it does not, you have an upstream installation issue with your camera / the integration for the camera, and need to resolve that first. Your issue is not related to the card itself.
2. Check whether any URLs specified in your card configuration are accessible from the network of the browser.
3. Check whether or not there are helpful clues shown on your Javascript console (F12 in many browsers) that might indicate the source of the issue.
4. Check you are using the latest version of all relevant camera integrations (e.g. Frigate).
5. If you're using a Frigate camera and are requesting a webrtc stream, ensure you have configured Frigate accordingly.
6. Search for your symptoms on the card issues page and see if you find any prior relevant discussions.

If you're happy with just using an image stream but want the small circle to go away, use the image live provider.

Unknown Command

Camera initialization failed: Unknown command

Your Frigate integration may not be up to date. Check the latest Frigate Integration releases.

Other Issues

2-way audio doesn't work

There are many requirements for 2-way audio to work. See Using 2-way audio for more information about these. If your microphone still does not work and you believe you meet all the requirements try eliminating the card from the picture by going directly to the go2rtc UI, navigating to links for your given stream, then to webrtc.html with a microphone. If this does not work correctly with 2-way audio then your issue is with go2rtc not with the card. In this case, you could file an issue in that repo with debugging information as appropriate.

Android will not render >4 JSMPEG live views

Android Webview (as used by Android Chrome / Android Home Assistant Companion) appears to severely limit the number of simultaneous OpenGL contexts that can be opened. The JSMPEG player (that this card uses), consumes 1 OpenGL context per rendering.

This limitation may be worked around (at a performance penalty) by disabling OpenGL for JSMPEG live views:

live:
  jsmpeg:
    options:
      disableGl: true

This bug has some more discussion on this topic. New ideas to address this underlying limitation most welcome!

Autoplay in Chrome when a tab becomes visible again

Even if live.auto_play or media_viewer.auto_play is set to [], Chrome itself will still auto play a video that was previously playing prior to the tab being hidden, once that tab is visible again. This behavior cannot be influenced by the card. Other browsers (e.g. Firefox, Safari) do not exhibit this behavior.

Blank white image on live view

For some slowly loading cameras, for which Home Assistant stream preloading is not enabled, Home Assistant may return a blank white image when asked for a still. These stills are used during initial Advanced Camera Card load of the live view if the live.show_image_during_load option is enabled. Disabling this option should show the default media loading controls (e.g. a spinner or empty video player) instead of the blank white image.

Casting to Chromecast broken

This could be for any number of reasons. Chromecast devices can be quite picky on network, DNS and certificate issues, as well as audio and video codecs. Check your Home Assistant log as there may be more information in there.

Tip

For Frigate to support casting of clips, the default ffmpeg settings for Frigate must be modified, i.e. Frigate does not encode clips in a Chromecast compatible format out of the box (specifically: audio must be enabled in the AAC codec, whether your camera supports audio or not). See the Frigate Home Assistant documentation or this issue for more.

Custom element does not exist

This is usually a sign that the card is not correctly installed (i.e. the browser cannot find the Javascript). In cases where it works in some browsers / devices but not in others it may simply be an old browser / webview that does not support modern Javascript (this is occasionally seen on old Android hardware). In this latter case, you are out of luck.

double_tap does not work in Android

The Android video player swallows double_tap interactions in order to rewind or fast-forward. Workarounds:

• Use hold instead of double_tap for your card-wide action.
• Use an Advanced Camera Card Element or menu icon to trigger the action instead.

Dragging in carousels broken in Firefox

The Firefox video player swallows mouse interactions, so dragging is not possible in carousels that use the Firefox video player (e.g. clips carousel, or live views that use the frigate or webrtc-card provider). The next and previous buttons may be used to navigate in these instances.

Dragging works as expected for snapshots, or for the jsmpeg provider.

Dragging video control doesn't work in Safari

Dragging the Safari video controls "progress bar" conflicts with carousel "dragging", meaning the video controls progress bar cannot be moved left or right. Turning off carousel dragging (and using next/previous controls) will return full video controls in Safari:

live:
  draggable: false
media_viewer:
  draggable: false

Downloads don't work

Downloads are assembled by the Frigate backend out of ~10s segment files. You must have enough cache space in your Frigate instance to allow this assembly to happen -- if large downloads don't work, especially for recordings, check your Frigate backend logs to see if it's running out of space. You can increase your cache size with the tmpfs size argument, see Frigate documentation.

Large downloads may take a few seconds to assemble, so there may be a delay between clicking the download button and the download starting.

Forbidden media source identifier

• If you are using a custom client_id setting in your frigate.yml file (the configuration file for the Frigate backend itself), you must tell the card about it. See Frigate engine configuration.
• You must have the Enable the media browser option enabled for the Frigate integration, in order for media fetches to work for the card. Media fetches are used to fetch events / clips / snapshots, etc. If you just wish to use live streams without media fetches, you can use the following configuration:

live:
  controls:
    thumbnails:
      mode: none

Fullscreen doesn't work on iPhone

Unfortunately, iOS does not support the Javascript fullscreen API on the iPhone, which severely limits the fullscreen functionality available. On iPhone, fullscreen is only possible of the selected video element. As a result, there will be no menu, status bar, grid support, gallery / timeline support, nor support for non-video based live providers such as image or jsmpeg -- exclusively viewing a selected live video or media video in fullscreen.

The card will only show the fullscreen menu button when fullscreen can usefully be activated, which means for certain views on the iPhone it will be absent.

Custom go2rtc server only works on Home Network

This card runs in your browser, and (if configured) attempts to opens a direct connection to a go2rtc server. If you are manually specifying a custom server using the url option, your browser may only be able to access that server when you're on the same network, and/or when both Home Assistant and the go2rtc server are both accessed over http or both over https.

To automatically proxy the connection via the Home Assistant process instead (ensuring that if you can access the card, you'll always have access to the go2rtc server), optionally install hass-web-proxy-integration and your connection will be automatically proxied. See proxying.

iOS App not updating after card version change

Try resetting the app frontend cache:

• Configuration -> Companion App -> Debugging -> Reset frontend cache

Javascript console errors

[Violation] Added non-passive event listener to a scroll-blocking [...] event

This card uses visjs -- a timeline library -- to show camera timelines. This library currently uses non-passive event-listeners. These warnings can be safely ignored in this instance and cannot easily be fixed in the underlying library.

Microphone menu button not shown

The microphone menu button will only appear if both enabled (see Menu Button configuration) and if the media that is currently loaded supports 2-way audio. See Using 2-way audio for more information about the requirements that must be followed.

Picture-in-Picture only shows video but not other card controls

Picture-in-Picture (PIP) uses the browser's native video PIP API which floats the raw video element into a small window. This means:

• No card UI in the PIP window. Only the video itself is shown — no menu, status bar, timeline, or other card elements. The card remains fully functional on the dashboard behind it.
• Limited browser support. Not all browsers support the PIP API. See Can I use: Picture-in-Picture for current browser compatibility.
• Non-video live providers are not supported. Providers such as image or jsmpeg do not use a native <video> element so PIP is unavailable for these.

A more fully featured PIP mode (showing the entire card in a floating window) was explored using the experimental Document Picture-in-Picture API, however it proved unworkable: Home Assistant state updates cannot reach a card in a separate document, and browser-managed styles (adoptedStyleSheets) are cleared when elements move between documents — resulting in an unstyled, non-updating card.

New version not working in Chrome

When upgrading the card it's recommended to reset the frontend cache. Sometimes clearing site data in Chrome settings isn't enough.

• Press F12 to display Dev Console in Chrome then right click on the refresh icon and select Empty Cache and Hard Reload

Static image URL with credentials doesn't load

Your browser will not allow a page/script (like this card) to pass credentials to a cross-origin (different host) image URL for security reasons. There is no way around this unless you could also control the webserver that is serving the image to specifically allow crossorigin requests (which is typically not the case for an image served from a camera, for example). The stock Home Assistant Picture Glance card has the same limitation, for the same reasons.

Status "popup" continually popping up

Status popup can be disabled with this configuration:

status_bar:
  style: none

Too many releases!

A new version of this card is automatically released on each change ("Pull Request"). This means features and fixes are available immediately! However, it also means there may be visual notifications in Home Assistant frequently recommending update and some users find this annoying.

The topic of intentionally doing fewer releases has been discussed fairly extensively (#1781, #2072) but it always comes down to some users (and this developer!) like it instant / often, others like it slower / rarer.

As a workaround for those that this bothers, the visual notification (the 'dot') to remind users to upgrade can be disabled by disabling the matching update entity provided by HACS. The entity is usually called update.advanced_camera_card_update. To disable it:

• Navigate to: Settings -> Devices & Services -> HACS -> # Entities -> Advanced Camera Card update
• Click the settings "cog"
• Set "Enabled" to off

Unknown Frigate instance frigate

e.g. API error whilst subscribing to events for unknown Frigate instance frigate

If you are using a custom client_id setting in your frigate.yml file (the configuration file for the Frigate backend itself), you must tell the card about it via the client_id parameter:

cameras:
  - camera_entity: camera.my_frigate_camera
    frigate:
      client_id: my-frigate

See Frigate engine configuration for more details.

If you're not using a custom client_id, your Frigate integration is likely not installed correct.

webrtc_card unloads in the background

AlexxIT's WebRTC Card which is embedded by the webrtc_card live provider internally disconnects the stream when the browser tab is changed (regardless of any Advanced Camera Card configuration settings, e.g. lazy_unload). To allow the stream to continue running in the background, pass the background argument to the webrtc_card live provider as shown below. This effectively allows the Advanced Camera Card to decide whether or not to unload the stream.

live:
  webrtc_card:
    background: true