Troubleshooting

Troubleshooting

Card Does Not Update After Installing

Refresh the browser or reload Home Assistant frontend resources.

For manual installs, check that the resource points to:

/local/orbit-cards.js

and that the resource type is JavaScript module.

Old Room Card Still Works

This is expected.

custom:orbit-room-card remains registered as a legacy alias for custom:orbit-area-card.

Open the card in the visual editor and save it to migrate the config to the new Area Card type.

Navigation Path Is Missing From The Editor

Navigation is now configured through the Interactions section as the card tap_action.

Use:

tap_action:
  action: navigate
  navigation_path: /dashboard-main/lounge

Legacy navigate.navigation_path configs still work as a fallback.

Theme Colours Do Not Appear

Reload themes in Home Assistant, then refresh the dashboard editor.

The picker reads colours from the active Home Assistant theme. Theme-provided colours are marked with T.

Local Icons Do Not Appear

Create:

/config/www/icons/manifest.json

Example:

[
  "motion_detected.svg",
  "motion_on.svg",
  "motion_off.svg"
]

Then refresh the editor.

SVG Icon Colours Look Wrong

Orbit Cards recolour inline SVG icons by default.

To preserve a multi-colour SVG, set the matching override to false:

icon_svg_color_override: false
button1_icon_svg_color_override: false
curve_button1_icon_svg_color_override: false

Add To Dashboard Preview Clicks

In Home Assistant's add-card picker, clicking a card preview should add the card. Inside the Orbit visual editor, preview interactions remain testable.

If preview clicks behave oddly, refresh the frontend resources and make sure only one copy of orbit-cards.js is registered.

Deck Card Child Editor Does Not Show

Deck Card asks Home Assistant for the selected child card's editor.

If the child card or badge supports a visual editor, it appears inside Deck Card's Card section. If the child does not expose a visual editor, Home Assistant shows YAML editing for that child instead.

If the editor area stays blank after adding a child card, save the card, refresh the dashboard editor, and reopen it.

Deck Card Padding Does Not Apply

Padding is configured per deck item under attributes.

decks:
  - attributes:
      force_padding: true
      padding_top: 5px
      padding_bottom: 0px
      padding_left: 0px
      padding_right: 0px
    card:
      type: custom:gauge-card-pro
      entity: sensor.main_import_power

Some child cards manage their own padding. Enable force_padding when Deck Card should override the child card's padding support.

If force_padding is off, a child card with its own padding support may keep control of its internal spacing.

Deck Card Actions Do Not Fire

Deck Card action overrides live under each deck item's attributes.

decks:
  - attributes:
      tap_action:
        action: navigate
        navigation_path: /dashboard-energy
    card:
      type: tile
      entity: sensor.main_import_power

If no Deck Card action is configured, the child card keeps its own action behaviour.

Overlay Child Is The Wrong Size

Overlay cards and badges use their natural size when attributes.width and attributes.height are unset.

Deck Card offers two fit modes:

• resize scales the child to the configured dimensions and is the default.
• crop keeps the child's scale and clips it to the configured dimensions.

If only width or height is configured in Resize mode, Deck Card preserves the child's aspect ratio.

Overlay Child Has An Unwanted Card Surface

Enable the per-item transparent background option, or set:

decks:
  - attributes:
      transparent_background: true
    badge:
      type: entity
      entity: binary_sensor.front_door

This removes the overlaid child's background, border, and shadow so it can blend into the main card.

The same attributes.transparent_background switch is available for Wrap and Tabs items. Tabs and joined Wrap layouts enable it by default; set it explicitly to false when the child should keep its own surface.

Deck Card Child Visibility Does Not Apply

Put Home Assistant visibility conditions inside the child card or badge config, not inside Deck Card attributes:

decks:
  - attributes:
      name: Energy
    card:
      type: entities
      entities:
        - sensor.main_import_power
      visibility:
        - condition: state
          entity: input_boolean.show_energy
          state: "on"

Child visibility is supported in Wrap and Tabs layouts. It is intentionally not applied in Overlay layout, where children use fixed positions.

Template Does Not Update Or Shows An Error

New Orbit templates use Home Assistant's native Jinja renderer and should include Jinja delimiters:

state_template: >-
  {{ states('sensor.example') | float(0) > 0 }}

Open and save older Area or Status cards in the visual editor to migrate supported legacy bare expressions automatically. The Status Badge editor also shows native template-rendering errors below the affected field.