View source for Postmortems/2026-05-07 n8n HA Credential Repair

''As of: 2026-07-05 — migrated from `postmortems/2026-05-07-n8n-ha-credential-repair.md`''

= Postmortem: n8n Credential Failures & HA Workflow Repair =

'''Date:''' 2026-05-07  
'''Duration:''' ~6 hours of cascading failures (backup alerts since 2026-03-11 DB recovery)  
'''Severity:''' Medium — silent failures, no data loss, but monitoring blind spots  
'''Status:''' Resolved

----

== Summary ==

After the March 2026 n8n SQLite DB recovery, 12 workflows were silently failing due to stale/placeholder credential IDs. Home Assistant workflows had additional issues: wrong credential format, missing entity IDs, and parallel-merge node connections that n8n can't execute correctly.

----

== Root Causes (in order discovered) ==

=== 1. Stale SSH credential IDs from DB recovery ===
The March 2026 DB recovery recreated credentials with new IDs, but workflow JSONs stored on disk still had old IDs. When workflows were re-imported they referenced credentials that no longer existed.

* <code>CREDENTIAL_ID</code> — literal placeholder, never substituted  
* <code>S2muq5nzJFa5ZydC</code> — old SSH credential from pre-recovery DB

'''Current correct SSH credential ID:''' <code>2ugS1ibsZu1LQid8</code>

=== 2. Missing <code>homeAssistantApi</code> credential ===
The <code>homeAssistantApi</code>-type credential (different from <code>httpHeaderAuth</code>) was lost in the DB recovery. Eight workflows referenced ID <code>6CIwjyqyUwnvaezn</code> which no longer existed.

=== 3. Wrong credential <code>host</code> field format ===
n8n's <code>homeAssistantApi</code> credential uses '''separate <code>host</code> and <code>port</code> fields''' — the host is just the IP/hostname with no scheme, no port:

<syntaxhighlight lang="json">
{
  "host": "192.168.0.140",
  "port": 8123,
  "accessToken": "...",
  "ssl": false
}
</syntaxhighlight>

'''Wrong formats tried (and why they fail):'''
* <code>"host": "http://homeassistant.local:8123"</code> → Docker can't resolve <code>.local</code> mDNS names  
* <code>"host": "http://192.168.0.140:8123"</code> → node builds URL as <code>http://http://192.168.0.140:8123</code> → DNS lookup of literal string <code>"http"</code> → <code>EAI_AGAIN</code>  
* <code>"host": "192.168.0.140:8123"</code> → node builds URL as <code>http://192.168.0.140:8123:8123</code> → <code>ERR_INVALID_URL</code>

'''How discovered:''' Read the actual compiled source at:
<syntaxhighlight lang="text">
docker exec n8n find /usr/local/lib/node_modules/n8n -path "*HomeAssistant/GenericFunctions.js"
</syntaxhighlight>
URL construction: `<code> </code>${ssl?'https':'http'}://${credentials.host}:${credentials.port}/api${resource}<code> </code>`

=== 4. Missing entity IDs in HA node parameters ===
The <code>entityId</code> field was never saved in the original workflow JSONs exported from n8n. All HA state-read nodes had <code>resource: "state"</code> but no <code>entityId</code>.

'''Correct entity IDs used:'''

{| class="wikitable"
|-
! Node purpose
! Entity ID
|-
| Living room temp
| <code>sensor.ewelink_snzb_02p_temperature</code>
|-
| Beta sensor temp
| <code>sensor.temp_sensor_beta_temperature</code>
|-
| Closet/Charlie temp
| <code>sensor.temp_sensor_charlie_temperature</code>
|-
| Closet/Charlie humidity
| <code>sensor.temp_sensor_charlie_humidity</code>
|-
| Door sensor
| <code>binary_sensor.shellydw2_075374_door</code>
|-
| Weather forecast
| <code>weather.forecast_ronwood</code>
|-
| Phone next alarm
| <code>sensor.pixel_7_next_alarm</code>
|-
| Announce/TTS
| <code>media_player.home_assistant_voice_098a64</code>
|-
| HA notify
| <code>notify.home_assistant</code>
|}

=== 5. Parallel-merge node connections ===
Workflows had multiple HA nodes connected in '''parallel''' (all from the trigger), all feeding into one downstream code node. n8n runs the downstream node as soon as the first upstream node finishes — so the code crashes with <code>"Node X hasn't been executed"</code> when it tries to read data from the still-running nodes.

'''Pattern causing the bug:'''
<syntaxhighlight lang="text">
Trigger ──┬── Get Temp A ──┐
          ├── Get Temp B ──┼── Analyze  ← runs on first finish, others not done
          └── Get Temp C ──┘
</syntaxhighlight>

'''Fix — chain them sequentially:'''
<syntaxhighlight lang="text">
Trigger → Get Temp A → Get Temp B → Get Temp C → Analyze
</syntaxhighlight>

Each node passes its result downstream; the code node then accesses all previous nodes via <code>$('Get Temp A').first()</code> etc.

'''Affected workflows:'''
* Server Closet Monitor (Temp + Humidity)
* Home Temperature Alert (3 temp sensors)
* Morning Briefing (Weather + Energy Usage)
* Bedtime Routine (Door check + Weather)

----

== Diagnostic Approach ==

'''How to find execution errors when the n8n API returns no detail:'''
<syntaxhighlight lang="bash">
# execution_data table has the full run data
sudo sqlite3 /var/lib/docker/volumes/n8n-app_n8n_data/_data/database.sqlite \
  "SELECT substr(ed.data,1,5000) FROM execution_entity ee 
   JOIN execution_data ed ON ee.id = ed.executionId 
   WHERE ee.id = <EXEC_ID>;"
# Then grep for: EAI_AGAIN, ENOTFOUND, ERR_INVALID_URL, "message", getaddrinfo
</syntaxhighlight>

'''How to find which credentials are broken:'''
<syntaxhighlight lang="bash">
# Valid credential IDs in DB
sudo sqlite3 /var/lib/docker/volumes/n8n-app_n8n_data/_data/database.sqlite \
  "SELECT id, name, type FROM credentials_entity ORDER BY name;"

# Scan all workflows for IDs not in that list
# (see the audit script logic used in this session)
</syntaxhighlight>

'''After any credential fix — n8n must be restarted:'''
<syntaxhighlight lang="bash">
sudo -E sh -c 'cd /library/n8n-app && docker compose restart n8n'
</syntaxhighlight>
n8n caches credential validation state. Even after fixing a credential in the DB, workflows show "has issues" until restart.

----

== Current Credential IDs (verified 2026-05-07) ==

{| class="wikitable"
|-
! ID
! Name
! Type
|-
| <code>2ugS1ibsZu1LQid8</code>
| Stronghold SSH (mnw)
| sshPrivateKey
|-
| <code>4RowxM0jrmYDnctK</code>
| Home Assistant API
| homeAssistantApi
|-
| <code>w0gXpM8W793fahAY</code>
| ntfy Auth
| httpHeaderAuth
|-
| <code>x5tv5aXs5N5nd2aK</code>
| Matrix Bot (Zordon)
| httpHeaderAuth
|-
| <code>R9LGxXIhmWCRM5Cn</code>
| Home Assistant API (old httpHeaderAuth)
| httpHeaderAuth
|-
| <code>5MCznsMsxjqOrlhJ</code>
| AudioBookshelf API
| httpHeaderAuth
|-
| <code>XB0V2UwPdWkRJoWj</code>
| OpenAI Bearer
| httpHeaderAuth
|-
| <code>NIQrbnzjhpNzBV1P</code>
| OpenAi account
| openAiApi
|}

'''HA credential data format (correct):'''
* host: <code>192.168.0.140</code> (IP only, no scheme, no port)
* port: <code>8123</code>
* ssl: <code>false</code>
* accessToken: from Vaultwarden → "Home Assistant Long-Lived Token"

----

== Prevention ==

# '''After any n8n DB recovery:''' run the credential audit script before assuming workflows work. Check every active workflow's credential IDs against <code>credentials_entity</code>.
# '''Export workflow JSONs immediately after any credential re-creation''' so the repo stays in sync.
# '''Never use <code>homeassistant.local</code> in n8n''' — Docker containers can't resolve mDNS. Always use <code>192.168.0.140</code>.
# '''n8n parallel-merge pattern is broken''' — if multiple nodes need to read data before a code node, chain them sequentially, not in parallel.
# '''Test workflows after changes''' — check n8n execution history within 30 min of any credential/workflow change.