SmartThings Edge drivers are the local-first architecture Samsung introduced in 2022 that let Zigbee, Z-Wave, and Matter devices run their logic on the hub instead of in the cloud. When they work, they cut latency dramatically. When one gets stuck loading (spinning wheel next to the device in the app, no state updates, cannot control), the diagnostic path is different from any other SmartThings issue. This guide covers the specific runtime failures that trap Edge drivers and the recovery sequence that avoids losing device settings.
What “stuck loading” actually means in Edge driver terms
An Edge driver is a Lua program running inside the SmartThings hub’s local runtime. When you see “loading” next to a device, the app is polling the hub for the driver’s current state and getting a “not ready” response. Three real states produce this:
- The driver crashed on startup and the hub is auto-restarting it in a loop.
- The driver is waiting for a network response from the device that is not coming (Zigbee association timeout, Z-Wave secure include failure).
- The driver is caught in a version mismatch: the driver expects hub firmware N+1 but hub is on N (or vice-versa) and the runtime refuses to load it.
The three look identical in the app but require different fixes. The way to distinguish is the SmartThings advanced web console: my.smartthings.com/advanced.
Reading the advanced console
- Open my.smartthings.com/advanced in a browser and sign in with the account that owns the hub.
- Click Devices in the left panel. Find the stuck device by name or ID.
- Under the device details, note the “Driver” section: driver name, version, and status.
- Click Drivers in the left panel, then find the driver by name. Note its version, its “Loaded” status, and any error message.
If the driver says “Loaded” but the device says “Loading,” the driver crashed after loading. If the driver says “Loading” itself, the runtime is stuck. If the driver says “Error,” a specific message appears (usually a Lua stack trace).
The recovery sequence for each state
| Console state | Cause | Fix |
|---|---|---|
| Driver: Loaded, Device: Loading | Driver crashed after startup | Restart driver via advanced console |
| Driver: Loading, no error | Runtime stuck on driver initialization | Reboot hub (unplug 30 seconds) |
| Driver: Error, message about version | Driver expects newer/older hub firmware | Update hub firmware, or roll back driver version |
| Driver: Error, message about Lua module | Driver depends on a Lua module the hub lacks | Reinstall driver from the driver channel |
| Driver: Loaded, Device: Loading, hub CPU high | Driver polling the device too aggressively | Look for competing drivers on the same device; delete duplicates |
The driver-channel gotcha
Edge drivers come from channels. The SmartThings default channel ships stable driver versions. Third-party channels (community-maintained on the SmartThings Community) ship experimental versions. If you enrolled in a community channel to get support for a specific device, updates to that channel can push a driver version that is incompatible with your hub firmware.
To check which channel a driver is from:
- Advanced console, Drivers, click the driver.
- Look for the “Channel” attribute in the details panel.
- If the channel is not “SmartThings Beta” or a Samsung official channel, note the community name.
To revert to the SmartThings default driver:
- Advanced console, Hubs, tap your hub, tap Drivers.
- Find the community driver, tap the three-dot menu, choose Disable.
- Return to the device, force it to re-select a driver by tapping the driver name and selecting the SmartThings-provided one.
- The device may show “Loading” briefly while the runtime swaps drivers.
The persistent case: driver keeps crashing on load
If restarting the driver, rebooting the hub, and swapping to the default channel all fail, the driver’s own code is at fault. Options:
- Wait 24 hours. Driver maintainers usually push a patch within a day of a widespread crash report.
- Check the SmartThings Community forum for that driver’s thread. Search “stuck loading” plus the driver name. There is usually a workaround from the maintainer.
- As a fallback, remove the device entirely and re-add it. The re-add flow lets you choose which driver handles the device, and you can pick a different one that supports your device model.
The specific case: Zigbee bulb with a stuck contact-sensor driver
An occasional bug: after a Zigbee bulb pairs, the hub sometimes assigns a wrong driver (contact sensor instead of bulb). The bulb loads the wrong driver, which fails to render on/off controls. The advanced console shows a driver like “zigbee-contact-sensor” attached to a device that is clearly a bulb.
- Advanced console, Devices, tap the bulb.
- Look at “Driver.” Tap Change Driver.
- Select “zigbee-color-bulb” or “zigbee-white-bulb” as appropriate.
- Wait 30 seconds. The bulb should now render on/off and dim controls in the app.
Frequently asked questions
Do Edge drivers work when my internet is out? Yes. That is their advantage. Local automations continue to run against local devices as long as the hub is powered.
Can I write my own Edge driver? Yes. Samsung publishes the Lua runtime and driver SDK. Development requires the SmartThings CLI and comfort with Lua.
What happens to my old Groovy DTH-based devices when I upgrade to a hub that only supports Edge? Samsung migrated most Zigbee and Z-Wave devices automatically. Custom Groovy DTHs (community-maintained) did not migrate; those devices need an Edge driver equivalent, usually from the same community maintainer.
Does removing an Edge driver delete devices that use it? No. The devices remain but show “Loading” until another driver is assigned or the same driver is reinstalled.
Can I run two versions of the same driver on one hub? No. Each hub loads one version of each driver name. Community channels sometimes rename drivers (my-zigbee-color-bulb versus zigbee-color-bulb) to allow parallel installations.
How much of the hub’s storage does an Edge driver use? Individual drivers are small, typically 50-500 KB. The SmartThings v3 hub has enough storage for hundreds of drivers, and even a heavily-populated system rarely exceeds 20 MB of driver code total.
Does an Edge driver crash impact other devices’ drivers? Runtime isolation is designed to prevent this, but observed behavior on hub firmware before mid-2026 shows crashed drivers occasionally freezing the Lua runtime for 30-60 seconds, briefly stalling all local automations. Newer firmware isolates crashes more reliably.
Where can I find logs from a specific driver? Advanced console, Hubs, tap the hub, tap Driver Logs, filter by driver name. Logs retain the last few hours of activity. For deeper debugging, install the SmartThings CLI and stream live logs from your development machine.
