---
title: "Troubleshooting"
description: "Fixes for widget development and publishing problems. SDK version mismatches, preview rendering, and publish failures."
canonical: https://glasshome.app/docs/widgets/troubleshooting
section: "Support"
updated: 2026-08-10
---
# Troubleshooting

Author-facing fixes. User-facing dashboard problems (blank UI, entities, tunnels) live in [Dash → Troubleshooting](/docs/dash/troubleshooting). If nothing matches, ask in [Discord](https://discord.gg/FJYdeDmrzv).

<h2 id="incompatible-sdk">Users report "incompatible SDK" on install</h2>

Your widget was built against a newer `@glasshome/widget-sdk` than the user's dashboard supports.

- Check the `sdkVersion` range in your manifest; widen it if your widget doesn't actually need the newer APIs.
- Or publish a build against the older SDK alongside the new one; the registry serves each dashboard the newest compatible version.
- The dashboard-side fix (the user updating Dash) is in [Dash → Troubleshooting](/docs/dash/troubleshooting#widget-sdk).

See [Widget SDK](/docs/widgets/widget-sdk) for how `sdkVersion` resolution works.

<h2 id="preview-renders">Preview images missing or stale on the Hub page</h2>

Previews are produced from the `examples` you declare, at publish time.

- No images at all: the widget declares no `examples`. See [Widget Previews](/docs/widgets/widget-previews).
- Stale images: previews regenerate per published version. Publish a new version after changing example configs; editing metadata alone does not re-render.
- A broken render usually means the example config fails validation against your own schema; run `widget preview` locally to reproduce.

<h2 id="publish-fails">Publish fails from the CLI</h2>

- CLI below the enforced floor: Hub rejects old CLIs; the current minimum is served from `/api/widgets/cli-version`. Update with your package manager. See [Widget CLI → Version requirements](/docs/widgets/widget-cli#version-requirements).
- Scope errors: publishing under an organization requires membership with the publisher role. See [Organizations](/docs/hub/organizations).
- Manifest validation errors print the failing field; fix and re-run. The manifest schema is documented in [Publishing](/docs/widgets/widget-publishing).