How To Import Thread Credentials In Home Assistant: 3-Step Easy Setup Checklist

how to import thread credentials in home assistant — a concise, beginner-friendly checklist to import Thread/Matter credentials into Home Assistant using a single-stick SkyConnect, verify the result, and recover from common failures.

• Avoid wasted time: Exact prerequisites to check before importing Thread credentials
• One-stick SkyConnect: Minimal, safe USB → import checklist you can complete in 10–15 minutes
• Importing credentials from non‑Home‑Assistant border routers (Apple, Google, third‑party): what works — and what’s missing
• Verify success: exact UI indicators, logs to check, and device-join tests that prove the import worked
• Common beginner mistakes that break the import (and how to avoid them)
• Real-world failure modes and exact recovery steps (duplicate network IDs, devices won’t rejoin, and when to factory-reset)
• One-page printable quick-start & checklist (prereqs → import → verify → rollback)
• Conclusion
• FAQ

Avoid wasted time: Exact prerequisites to check before importing Thread credentials

Before you try to import Thread credentials, confirm these exact items so you don’t waste time troubleshooting hardware or network issues.

Required platform and software

• Home Assistant hub running Home Assistant OS (Home Assistant Green, Yellow, or Raspberry Pi). Keep HA updated before you start — the Thread integration appears automatically when a border router is detected (Home Assistant Thread docs — home-assistant.io/integrations/thread/ — 2024-10-01).
• The Home Assistant Companion app (Android or iOS) on a phone that is on the same LAN as your Home Assistant hub (same subnet) — required for importing credentials from other border routers (same source, 2024-10-01).

Border-router hardware and firmware

• USB Thread radio such as Home Assistant SkyConnect or an equivalent adapter. For multiprotocol adapters, ensure the radio is running OpenThread firmware — Zigbee firmware will not expose a Thread border router.
• Use a short USB extension cable and plug into a mainboard USB port. Avoid passive hubs that may sleep or change device nodes.

USB node & permissions

• Confirm the serial/tty device node is visible to HA (check Settings > System > Hardware or the USB devices page). If you need help, follow the USB permission notes in our home-assistant-basics: USB devices & permission troubleshooting guide.

Pitfall to avoid: assuming any multiprotocol stick is ready — many sticks ship in Zigbee mode. If the stick isn’t in OpenThread mode, HA will not detect the border router.

One-stick SkyConnect: Minimal, safe USB → import checklist you can complete in 10–15 minutes

This is the fastest reliable flow for a single-stick SkyConnect setup. Follow steps in order and stop if detection fails — diagnose before repeating imports.

1. Power down the HA hub, plug SkyConnect into a short USB extension and into a main USB port, then boot HA.
2. Confirm the device appears under Settings > System > Hardware (look for a serial/USB device). If not visible, see USB permission troubleshooting.
3. Verify SkyConnect is running OpenThread firmware. If your stick is multiprotocol, follow the vendor steps to flash OpenThread (see Thread docs — home-assistant.io/integrations/thread/ — 2024-10-01). If you don’t know how to flash, consult the vendor page or the integrations & add-ons guide for multiprotocol notes.
4. Open the Home Assistant Companion app on your phone (same LAN). On Android: Settings > Devices & services > Thread > Configure > Import Credentials. On iOS: use the Companion app option to send credentials to Home Assistant (follow on-screen prompts). Reference: HA Thread integration guide (2024-10-01).
5. In HA UI go to Settings > Devices & Services > Thread. The imported credentials will show as an icon and you can click “Make preferred network”. Select it and wait 30–60 seconds.
6. Test: commission a Matter-over-Thread device to the network (follow device-specific pairing). If it joins and appears in HA, success.

Restart hints: a full HA restart is usually not necessary after marking preferred, but if devices fail to join, restart HA and retry the Companion import.

Importing credentials from non‑Home‑Assistant border routers (Apple, Google, third‑party): what works — and what’s missing

The Companion app is the supported path for importing credentials from third-party routers, but vendor export steps are inconsistent or undocumented.

What works

• Use the Home Assistant Companion app to request credentials. Companion will attempt to read the local border router’s provisioning info and transfer it to HA (Thread docs — home-assistant.io/integrations/thread/ — 2024-10-01).

What’s missing / research gaps

• No reliable step-by-step vendor export instructions for Apple HomePod or Google Nest were found in the public docs. No reliable data found for vendor export procedures — next research steps: check Apple support and Google Nest developer docs, plus community threads for TLV or QR export methods.
• If you cannot export credentials from a vendor router, do not factory-reset your devices. Instead keep the device online and follow community recovery steps below.

Research task for authors: capture vendor pages for Google Nest, Apple HomePod, and GL.iNet (TLV/QR formats) and include screenshots or TLV export sequences in a future revision.

Verify success: exact UI indicators, logs to check, and device-join tests that prove the import worked

Verify on three fronts: HA UI, Companion app confirmations, and a real device join. Do not rely on one check only.

UI checks

• Thread integration shows imported credentials icon and exposes “Make preferred network” — this control appears when HA detects the border router and imported credentials (Home Assistant Thread docs — home-assistant.io/integrations/thread/ — 2024-10-01).
• Confirm the network is marked Preferred in Thread integration settings after import.

Companion app

• Look for the app success notification after the import. If it reports failure, use the Companion app troubleshooting flow and ensure the phone and HA hub are on the same subnet — see GH issue showing network mismatch blocks import (github.com/home-assistant/android/issues/3582 — 2023-07-01).

Logs & diagnostics

• Search Home Assistant logs for terms: thread, import, border-router, and errors such as “unknown type 74” if present. Community reports reference exact strings for troubleshooting (community thread: community.home-assistant.io/thread-import-credentials — 2023-10-01).
• If using the OS terminal, run: journalctl -u home-assistant@homeassistant.service (or view Supervisor logs) and grep for “thread” or “import”.

Device join test (step-by-step)

1. Remove device from its current controller if required (follow vendor pairing instructions).
2. Put the Matter-over-Thread device into commissioning mode (manufacturer steps).
3. In HA, use the Integrations > Matter or Thread flow to add new device. Confirm it appears and responds to basic commands (on/off, status).

Pitfall to avoid: not testing an actual device join. UI icons alone aren’t proof until a device successfully joins over Thread.

Common beginner mistakes that break the import (and how to avoid them)

These mistakes are frequent and simple to prevent.

• Wrong firmware mode: stick in Zigbee mode instead of OpenThread — verify or flash OpenThread first (Thread docs — 2024-10-01).
• USB port issues: using a sleeping hub or long passive hub that reassigns serial nodes — use a short extension and direct ports.
• Competing border routers: stop other routers (HomePods, Nest, other HA hubs) before importing to avoid keystore conflicts.
• Network mismatch: phone on guest Wi‑Fi or a different VLAN will block Companion import — ensure same LAN (see GH issue about network mismatch — github.com/home-assistant/android/issues/3582 — 2023-07-01).
• Expecting cloud-only transfers: vendor cloud will not automatically export Thread credentials to HA — use the Companion app export or vendor-specific steps.

Quick pre-start checklist: confirm HA OS updated, SkyConnect in OpenThread mode, phone on same LAN, USB extension used, and no other active border routers.

Real-world failure modes and exact recovery steps (duplicate network IDs, devices won’t rejoin, and when to factory-reset)

Community reports show a handful of repeatable failure modes. Use this exact recovery sequence before factory-resetting devices.

Known failures

• “unknown type 74” during import from HomePod Mini — reported in community thread (community.home-assistant.io/thread-import-credentials — 2023-10-01).
• Import loops or sync failures when Companion app cannot reach HA (network mismatch — github.com/home-assistant/android/issues/3582 — 2023-07-01).
• Conflicts with coexisting routers: devices bound to a different controller will not roam — see community discussion on border-router coexistence (community.home-assistant.io/border-router-coexistence — 2024-01-01).

Exact recovery sequence (recommended)

1. Stop or disconnect other border routers on the network (power down HomePods / Nest routers temporarily).
2. In HA UI: Settings > Devices & Services > Thread > click the three-dot menu and select Reset Thread Network (or use the UI reset option). If no UI option, stop the Thread service via Supervisor and restart HA. Note: No reliable data found for CLI commands to export/import the Thread keystore — next research: check the HA changelog and Supervisor docs for keystore CLI options.
3. Use the Companion app to re-import credentials to HA while only one border router (your SkyConnect) is active on the network.
4. Attempt a device rejoin. If the device still fails, only then consider a factory reset of the device following vendor guidance.

Backup & rollback: if a keystore export is supported by your HA version, export it before risky operations. No reliable data found for a standard keystore export workflow or exact OpenThread version requirements; research tasks: check Home Assistant changelog and vendor SkyConnect firmware pages.

One-page printable quick-start & checklist (prereqs → import → verify → rollback)

Print this checklist for the workbench. It’s minimal and action-oriented.

Prerequisites (check before you start)

1. HA hub running Home Assistant OS (updated). See home-assistant-basics: Installing Home Assistant OS and setting up your hub.
2. SkyConnect or Thread-capable USB radio available and a short USB extension cable.
3. Companion app installed on phone and on same LAN. See home-assistant-basics: Companion app setup and troubleshooting.
4. No other active Thread border routers on the same network (power them down temporarily).

Minimal import steps (numbered)

1. Attach SkyConnect via short USB extension to mainboard port; boot HA.
2. Confirm device visible in Settings > System > Hardware.
3. Ensure OpenThread firmware on SkyConnect; flash if needed (see Thread integration docs — home-assistant.io/integrations/thread/ — 2024-10-01).
4. Open Companion app (same LAN) and run Import Credentials → send to Home Assistant.
5. In HA Thread integration, select “Make preferred network” and wait 30–60s.
6. Commission a Matter-over-Thread device to confirm.

Verify (quick)

• Thread page shows imported credential icon and preferred flag.
• Companion app shows success message.
• Device successfully joins and responds to basic commands.

Rollback (3 steps)

1. Stop competing border routers.
2. Reset Thread network in HA (UI reset), re-import credentials.
3. Only factory-reset device if it still won’t rejoin after re-import.

Copy/paste command reminders: check logs with Supervisor → System → Logs, or use journalctl on a Linux HA install. For step-by-step multiprotocol setup see home-assistant-basics: Integrations & add-ons and the Matter overview home-assistant-basics: Matter integration overview.

Writer action: create a downloadable 1-page PDF of the above checklist for quick printing and attach to the article in the next revision.

Conclusion

Following the single-stick SkyConnect checklist above will let most beginners complete the import and verify Thread functionality without guessing. If you run into issues, follow the recovery sequence (stop other routers → reset Thread on HA → re-import) before factory-resetting devices. For further setup help, compare hardware and troubleshooting guides or read more in the Home Assistant Thread docs and community threads.

Want more: subscribe for updates, or read our linked guides on installing Home Assistant OS and USB troubleshooting to prepare your hub before trying how to import thread credentials in home assistant.

FAQ