Skip to content

Troubleshooting

Jump to bottom
老王杂谈说 edited this page Jul 21, 2026 · 2 revisions

🇨🇳 中文 | 🇺🇸 English

Home · Store · Changelog

Troubleshooting

Common issues and solutions when using Skins Pro.

⚠️ First Step: Clear Your Cache

Whenever you see broken layout, missing icons, or strange visual glitches — always start here.

  1. Hard refresh: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac)
  2. Clear browser cache: Chrome → Settings → Privacy → Clear browsing data → Cached images and files → All time
  3. Restart HA Companion App (mobile users)
  4. Try incognito/private mode — if it works there, cache is the issue

Cache issues are the #1 cause of "layout broken" reports. Skins Pro caches its CSS and JS aggressively through the browser and HA's frontend cache. A hard refresh fixes 90% of visual issues.

Symptoms: Dashboard shows a blank card, or the skin styles/images don't appear.

Solutions:

  1. Hard refresh — Press Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac) to bypass browser cache.

  2. Check resources — Go to Settings → Dashboards → Resources and verify:

    • /local/skins-pro.js (or /local/community/skins-pro/skins-pro.js) is listed
    • Type is set to JavaScript Module

  3. Check HACS installation — If installed via HACS, ensure the custom repository URL is correct: https://github.com/ha-china/Skins-Pro

  4. Browser console — Open DevTools (F12) → Console tab. Look for:

    • 404 errors on skins-pro.js — the file isn't at the expected URL
    • 404 errors on theme.css — skin assets aren't deployed
    • Lit errors — possible version mismatch

  5. Modern skin not loading — If the built-in modern skin images/styles are missing, copy dist/modern/ to your HA www/ folder:

    <HA config>/www/community/skins-pro/modern/

Icons Not Displaying

Symptoms: Environment sensor icons are blank, or weather icons are missing.

Solutions:

  1. Hard refresh — Clear browser cache first.

  2. Check entity state — Go to Developer Tools → States in HA and verify the entity has:

    • attributes.icon — user-set or integration-set icon
    • device_class — used for default icon resolution (e.g., humidity → mdi:water-percent)

  3. HA icon resolution — Skins Pro uses HA's native <ha-state-icon> component. If an icon shows in HA's standard UI but not in Skins Pro, it's likely a HA frontend version issue.

  4. Weather icons — Weather icons are also resolved via <ha-state-icon>. If the main weather icon works but forecast icons don't, check your HA version (2024+ required).

Card Editor Not Opening

Symptoms: Clicking the card doesn't show the editor, or the editor is blank.

Solutions:

  1. Check permissions — Ensure you're logged in as an admin user.

  2. Browser console errors — Look for JavaScript errors that might prevent the editor from rendering.

  3. Re-add the card — Remove the card from the dashboard and add it again.

Skin Store Download Fails

Symptoms: Clicking "Download" in the skin store doesn't work, or the download never completes.

Solutions:

  1. Install the integration — The skin store requires the skins-pro-hass integration. Install it from HACS or manually copy it to your custom_components/ folder.

  2. Check network — The skin store fetches from a CDN. Ensure your HA instance has internet access.

  3. Manual install — If the store doesn't work, you can manually download the skin and place it in:

    <HA config>/www/skins-pro/<skin-name>/

    Then add the skin name to downloaded_skins in the card editor.

Build Errors

Symptoms: npm run build fails with errors.

Solutions:

  1. Check Node.js version — Requires Node.js 18+.

  2. Reinstall dependencies:

    rm -rf node_modules
npm install

  3. TypeScript errors — Run npm run type-check to see specific type errors.

  4. Image processing errors — Ensure images are valid PNG/JPG/BMP/WebP files. Corrupted images will cause sharp to fail.

Kiosk Mode Issues

Symptoms: Kiosk mode doesn't activate, or non-admin users can exit kiosk.

Solutions:

  1. Admin users — Kiosk can be toggled by clicking the avatar. If it doesn't work, check that fullscreen is enabled in the card editor.

  2. Non-admin users — Kiosk is forced automatically. If a non-admin user can exit, ensure hass.user.is_admin is correctly reporting the user's role.

  3. Right-click still works — The right-click blocker prevents context menu on the card. If right-click still works on the HA sidebar, this is expected — the blocker only applies to the dashboard area.

Slow Performance

Symptoms: Dashboard is slow to load or lags when switching views.

Solutions:

  1. Reduce device count — Filter devices by area or type in the card editor.

  2. Limit environment sensors — Set home_limits.environment in the editor to limit the number of displayed sensors.

  3. Camera snapshots — Camera snapshots update every time the dashboard renders. Consider disabling the camera on the homepage if it's causing lag.

  4. Browser hardware acceleration — Enable hardware acceleration in your browser settings.

Reporting Issues

If the troubleshooting steps above don't help, please open an issue with:

  • Your HA version
  • Browser and version
  • Skins Pro version
  • Steps to reproduce
  • Screenshots or console logs (if applicable)

Clone this wiki locally