ESPHome Device Did Not Offer Encryption: Fix

Direct answer: An ESPHome invalid-encryption-key error means the device and Home Assistant do not share the same 32-byte base64 native API key. Copy the key from the device’s current ESPHome YAML or Device Builder configuration into the Home Assistant integration’s reconfiguration flow. If the device was flashed with a different key, update Home Assistant to that key; do not disable API encryption as a shortcut.

This article concerns ESPHome native API encryption, not Wi-Fi passwords, OTA passwords, dashboard login credentials, or MQTT authentication. ESPHome 2026.1 removed deprecated API password authentication and requires API encryption for secure native API use.

Symptoms and affected scope

The device is online and answers ping, but Home Assistant cannot connect.
Logs mention an invalid encryption key, Noise handshake failure, or authentication failure.
The problem began after adopting a device, restoring YAML, rotating secrets, or reflashing.
ESPHome logs work from one installation but Home Assistant shows the device unavailable.

These symptoms can look similar even though their causes sit in different layers. The safest approach is to preserve the current working state, identify the first failing layer, and change one variable at a time. This prevents a recoverable ESPHome invalid encryption key problem from turning into lost pairings, lost entities, or an inaccessible installation.

Ranked likely causes

1. Home Assistant stores an old key while the device firmware contains a new one.
2. The YAML references the wrong secret, or two devices unintentionally share or swap secret names.
3. A copied key includes spaces, quotes, truncation, or invalid base64.
4. The device was adopted or recompiled from a different ESPHome installation.
5. YAML indentation or a merge placed the encryption key outside the api.encryption block.
6. The user is changing the OTA password or Wi-Fi key instead of the native API key.

Before changing anything

Make a current backup, record versions and installation type, capture the exact first error, and remove secrets from any notes. Do not delete integrations, reset devices, erase databases, or reflash firmware as an opening move. If equipment is hot, swollen, wet, arcing, smoking, or connected to mains wiring that must be opened, stop and use qualified help.

Least-destructive diagnostic order

1. Confirm the device is powered, on the expected network, and reachable at its current address. An unreachable device cannot prove an encryption mismatch; solve power, Wi-Fi, DHCP, and VLAN routing first. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
2. Open the device’s current ESPHome configuration. Locate api, then encryption, then key. If the key uses !secret, open the matching secrets file locally. Never paste the key into public logs, forums, screenshots, or diagnostic exports. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
3. Verify the key belongs to this exact device. A valid ESPHome API key is a 32-byte value represented as base64; visual similarity is not enough when several devices use generated keys. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
4. In Home Assistant, open Settings → Devices & services → ESPHome and choose Reconfigure for the affected entry when available. Enter the device’s current key and submit the flow. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
5. If reconfigure is unavailable, record the device name, entities, automations, and current address before removing anything. Prefer reauthentication or reconfiguration over deleting the integration. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
6. Validate the YAML structure. The encryption block must be nested under api. Check recent ESPHome validation output for warnings about misplaced keys or YAML merges. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
7. If the source configuration is lost but OTA access still works from the ESPHome installation that built the device, restore the project or compile a controlled update with a new unique key. Keep the device powered and close to reliable Wi-Fi during the update. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
8. If neither the source key nor OTA access exists, physical serial recovery may be required. Back up any available configuration first and follow the board-specific flashing procedure. Disconnect mains-powered hardware and use a qualified person where enclosure access exposes hazardous voltage. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
9. After rotating a key, update Home Assistant immediately and store the new secret in the appropriate local secrets file. Do not reuse one key across every ESPHome device. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
10. Restart only the ESPHome integration or device entry after the key is corrected. Rebooting all of Home Assistant is rarely needed and can hide the sequence that fixed the problem. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.

Choose the correct branch

Online device with known YAML: update the Home Assistant config entry; no reflash is needed.
Known key but wrong YAML nesting: correct YAML, validate, and flash only if the device firmware must change.
Lost key with working OTA builder: generate a new unique key and perform a controlled OTA update.
Lost key and no OTA access: use documented physical recovery; do not guess keys or disable network security.

How to interpret the results

If the evidence points to Home Assistant stores an old key while the device firmware contains a new one. Correct only that layer, then repeat the smallest relevant test. If the result does not change, restore the prior value and continue; do not stack speculative fixes.

If the evidence points to the YAML references the wrong secret, or two devices unintentionally share or swap secret names. Correct only that layer, then repeat the smallest relevant test. If the result does not change, restore the prior value and continue; do not stack speculative fixes.

If the evidence points to a copied key includes spaces, quotes, truncation, or invalid base64. Correct only that layer, then repeat the smallest relevant test. If the result does not change, restore the prior value and continue; do not stack speculative fixes.

If the evidence points to the device was adopted or recompiled from a different ESPHome installation. Correct only that layer, then repeat the smallest relevant test. If the result does not change, restore the prior value and continue; do not stack speculative fixes.

If the evidence points to YAML indentation or a merge placed the encryption key outside the api.encryption block. Correct only that layer, then repeat the smallest relevant test. If the result does not change, restore the prior value and continue; do not stack speculative fixes.

If the evidence points to the user is changing the OTA password or Wi-Fi key instead of the native API key. Correct only that layer, then repeat the smallest relevant test. If the result does not change, restore the prior value and continue; do not stack speculative fixes.

Verified repair and final checks

Confirm the device entry becomes available, native API logs show a successful connection, entity states update, one harmless command round-trips, and the connection remains stable after a device restart. Verify the corrected key is stored only in private configuration.

A repair is not verified merely because an error banner disappears. Confirm the underlying connection or service, observe fresh state data, and test after a controlled restart where appropriate. Keep the previous configuration until the new state has remained stable.

Rollback and recovery

Before a firmware update, retain the last working YAML and binary when possible. If a new build fails to connect, restore the prior known-good build by the safest available method. Never interrupt power during flashing.

Write down each change before making it. Reversibility matters: a documented URL, service setting, serial path, integration state, or firmware version is much easier to restore than a configuration changed in several places at once.

Prevention

Generate a unique API encryption key for every device, store it in secrets.yaml, back up ESPHome projects securely, label adopted devices, and review validation warnings before flashing.

Review this setup after platform, firmware, router, certificate, or host changes. Backups should exist off the device and should be periodically checked for visibility and required encryption material.

Privacy and safety

Never publish access tokens, API keys, encryption keys, Wi-Fi credentials, public IP addresses, precise locations, camera URLs, door-lock states, alarm details, or complete unsanitized diagnostics. Do not weaken TLS, firewall rules, authentication, or network isolation simply to make an error disappear.

Testing disclosure

This guide is based on the current official documentation and linked upstream reports. Troubliq did not physically test every device, adapter, network, phone, host, or installation variant described. Device-specific behavior can differ; preserve backups and follow the manufacturer’s safety instructions.

2026.9 OTA error: “device did not offer encryption”

This OTA message is different from a Home Assistant native-API key mismatch. In ESPHome 2026.9, the esphome OTA platform can encrypt firmware transfers with the native API encryption key. Older firmware cannot offer that encrypted OTA handshake. If the new YAML requires ota: encryption: before the device has received a 2026.9-or-newer transition build, ESPHome correctly refuses to send the firmware image in plaintext.

Use this least-destructive migration order

Do not generate a replacement API key. If Home Assistant provisioned the existing key, copy that same value into api: encryption: key:. A new key can lock Home Assistant out of the device.
Keep the existing OTA password for the transition build. Build with ESPHome 2026.9.0 or newer, include the existing API encryption key, but do not require OTA encryption yet. The old firmware still expects its password.
Install once and inspect the device log. The expected transition result is Encryption: offered, plaintext accepted. This confirms that the running firmware can negotiate encrypted OTA.
Only then require encryption. Replace the OTA password with the encryption: block, install again, and confirm Encryption: required.

If the device has no native API, the official procedure uses a temporary API block with a unique generated key and reboot_timeout: 0s for the transition. If neither OTA route is available, serial flashing or the deliberately configured web-server OTA platform is the recovery path. Do not weaken firewall rules, reuse keys between devices, or paste keys into forums.

How to interpret the result

A refusal before the transition build normally means the running firmware cannot offer encrypted OTA; it does not prove that Wi-Fi, DNS, or the board is broken. A password error means the old firmware still expects the former OTA password. An API connection failure after installing a newly generated key points to a key mismatch between the device and Home Assistant. Roll back by restoring the previous YAML and original secret values; never publish the compiled firmware because it can contain Wi-Fi credentials and encryption material.

Evidence and testing disclosure: This branch follows the official ESPHome 2026.9 release notes, OTA documentation, native API documentation, and security guidance. Troubliq has not physically tested every board, bootloader, network, or historical configuration. Last reviewed October 1, 2026.

Sources

Last reviewed: September 24, 2026.

Next: use the Home Assistant Error Decoder to match the exact message, or return to the current Home Assistant problems hub.

Detailed diagnostic reference

Distinguish the four secrets

Wi-Fi credentials join the network, the native API encryption key protects Home Assistant communication, the OTA credential protects firmware updates, and an MQTT password authenticates a broker. Changing one does not repair another; identify which subsystem produced the log message.

Validate base64 without exposing it

The API key represents 32 bytes in base64. Use ESPHome validation locally rather than pasting the secret into an online decoder. Quotation marks, whitespace, a truncated copy, or the wrong secret reference can make a visually plausible key invalid.

Trace secret resolution

When YAML uses !secret, confirm which secrets.yaml file the active Device Builder instance reads. A restored project or second ESPHome installation may resolve the same secret name to a different value. Record the builder that last compiled the device.

Check YAML hierarchy

The encryption block belongs beneath api. Mis-indentation can move it outside the component or cause a merge to replace the intended block. Treat validation warnings as build failures until the resulting configuration is understood.

Use reconfiguration before deletion

Home Assistant can often update the key through the ESPHome entry’s reconfigure flow. Deleting the entry may break entity identifiers and automations while leaving the actual key mismatch untouched. Preserve the registry relationship whenever possible.

Rotate deliberately

If the key may have leaked, generate a new unique key, update the device through the trusted builder, then update Home Assistant. Perform the steps in a controlled window so the old key is not lost before the new firmware is reachable.

Recover an adopted device

Identify the original YAML, substitutions, packages, board type, and pin assignments before compiling. A generic replacement file can connect while silently changing relays, sensors, restore modes, or safety interlocks.

Protect mains-powered devices

Do not open an energized relay, plug, light controller, or appliance to reach serial pins. Disconnect power and follow the manufacturer’s isolation procedure. If hazardous voltage may be exposed, use a qualified technician.

Check after reconnection

Inspect API logs for successful encrypted handshake, confirm entity availability and timestamps, test one harmless command, and restart the device once. A single online state immediately after flashing is not enough to prove stable recovery.

Completion criteria

The correct device connects using its unique key, no Noise or authentication warning returns, secrets remain private, OTA access is documented, and the saved project can reproduce the running firmware without hidden credentials.

ESPHome OTA encryption error: device did not offer encryption