Troubleshooting

Author-facing fixes. User-facing dashboard problems (blank UI, entities, tunnels) live in Dash → Troubleshooting. If nothing matches, ask in Discord.

Users report “incompatible SDK” on install

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.

See Widget SDK for how sdkVersion resolution works.

Preview images missing or stale on the Hub page

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

• No images at all: the widget declares no examples. See 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.

Publish fails from the CLI

• 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.
• Scope errors: publishing under an organization requires membership with the publisher role. See Organizations.
• Manifest validation errors print the failing field; fix and re-run. The manifest schema is documented in Publishing.