fix: retry HA Discovery TreeXML on C-Gate startup race

C-Gate accepts TCP connections on the command port before its project's
networks are loaded, so the initial TREEXML query at bridge startup could
return 401 "Network not found" and HA Discovery would silently give up.
Devices never appeared in Home Assistant even though events flowed normally.

HaDiscovery now retries failed TreeXML requests with exponential backoff
(2s up to 60s, max 8 attempts), driven by both the 401 fast-fail and an
8s no-response watchdog. Once the retry limit is exhausted, the warning
explains how to recover via cbus/write/<network>///gettree.

Bumps to 1.8.1.

Author: dougrathbone

homeassistant-addon/CHANGELOG.md

@@ -5,6 +5,11 @@ All notable changes to the C-Gate Web Bridge Home Assistant add-on will be docum
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.8.1] - 2026-05-04
+
+### Fixed
+- **HA Discovery startup race**: C-Gate accepts TCP connections on the command port before its project's networks are loaded, so the initial `TREEXML` query could return `401 Network not found` and HA Discovery would silently give up — devices never appeared in Home Assistant even though events flowed normally. `HaDiscovery` now retries failed TreeXML requests with exponential backoff (2s → 60s, up to 8 attempts), driven both by the `401 Network not found` fast-fail and an 8s no-response watchdog. After the retry limit, a clear warning explains how to recover via `cbus/write/<network>///gettree`.
+
 ## [1.8.0] - 2026-04-29
 
 ### Changed

homeassistant-addon/config.yaml

@@ -1,5 +1,5 @@
 name: "C-Gate Web Bridge"
-version: "1.8.0"
+version: "1.8.1"
 slug: cgateweb
 description: "Bridge between Clipsal C-Bus systems and MQTT/Home Assistant"
 url: "https://github.com/dougrathbone/cgateweb"

package.json

@@ -1,6 +1,6 @@
 {
   "name": "cgateweb",
-  "version": "1.8.0",
+  "version": "1.8.1",
   "description": "Node.js bridge connecting Clipsal C-Bus automation systems to MQTT for Home Assistant integration",
   "keywords": [
     "cbus",

src/bridgeInitializationService.js

@@ -305,8 +305,14 @@ class BridgeInitializationService {
      * Handles C-Gate command errors. If a 401 (not found) is received for a path
      * that is being periodically polled, the polling timer is cancelled to prevent
      * recurring error logs for apps that don't exist on this C-Bus installation.
+     * Also forwards 401 errors to HaDiscovery so it can retry TreeXML requests
+     * that fail because C-Gate hasn't finished loading networks at startup.
      */
     handleCommandError(code, statusData) {
+        if (this.bridge.haDiscovery && typeof this.bridge.haDiscovery.handleCommandError === 'function') {
+            this.bridge.haDiscovery.handleCommandError(code, statusData);
+        }
+
         if (code !== '401') return;
         // Extract network/app path from statusData like:
         // "Bad object or device ID: //CLIPSAL/254/203/* (Object not found)"
@@ -338,6 +344,9 @@ class BridgeInitializationService {
         this.bridge.labelLoader.unwatch();
 
         if (this.bridge.haDiscovery) {
+            if (typeof this.bridge.haDiscovery.stop === 'function') {
+                this.bridge.haDiscovery.stop();
+            }
             this.bridge.haDiscovery.removeAllListeners?.();
             this.bridge.haDiscovery = null;
             this.bridge.commandResponseProcessor.haDiscovery = null;

src/haDiscovery.js

@@ -69,6 +69,18 @@ class HaDiscovery {
         // Tracks all discovery config topics published in this session so that
         // stale retained messages can be cleared when devices are excluded or change type.
         this._publishedTopics = new Set();
+
+        // C-Gate accepts TCP connections on the command port before its project
+        // networks are loaded. Initial TREEXML can therefore return 401 "Network
+        // not found" until C-Gate finishes startup. These maps drive a
+        // per-network retry loop with exponential backoff so HA Discovery
+        // recovers automatically without restarting the bridge.
+        this._treeWatchdogs = new Map();   // networkId -> timeoutHandle
+        this._treeRetryState = new Map();  // networkId -> { attempts, retryHandle }
+        this._maxTreeRetryAttempts = 8;
+        this._treeRetryInitialDelayMs = 2000;
+        this._treeRetryMaxDelayMs = 60000;
+        this._treeRequestTimeoutMs = 8000;
     }
 
     /**
@@ -145,19 +157,136 @@ class HaDiscovery {
 
     queueTreeRequest(networkId) {
         const normalizedNetwork = String(networkId);
+
+        // Cancel any pending retry timer — we're sending a fresh request now.
+        this._cancelTreeRetry(normalizedNetwork, /* keepAttempts */ true);
+
         this.logger.info(`Requesting TreeXML for network ${normalizedNetwork}...`);
-        this.pendingTreeNetworks.push(normalizedNetwork);
+
+        // Avoid duplicate pending entries when a retry races a late response.
+        if (!this.pendingTreeNetworks.includes(normalizedNetwork)) {
+            this.pendingTreeNetworks.push(normalizedNetwork);
+        }
+
+        this._armTreeWatchdog(normalizedNetwork);
         this._sendCommand(`${CGATE_CMD_TREEXML} ${normalizedNetwork}${NEWLINE}`);
     }
 
+    _armTreeWatchdog(networkId) {
+        this._cancelTreeWatchdog(networkId);
+        const handle = setTimeout(() => {
+            this._treeWatchdogs.delete(networkId);
+            this._handleTreeRequestFailure(networkId, 'no response within timeout');
+        }, this._treeRequestTimeoutMs);
+        if (typeof handle.unref === 'function') handle.unref();
+        this._treeWatchdogs.set(networkId, handle);
+    }
+
+    _cancelTreeWatchdog(networkId) {
+        const handle = this._treeWatchdogs.get(networkId);
+        if (handle) {
+            clearTimeout(handle);
+            this._treeWatchdogs.delete(networkId);
+        }
+    }
+
+    _cancelTreeRetry(networkId, keepAttempts = false) {
+        const state = this._treeRetryState.get(networkId);
+        if (!state) return;
+        if (state.retryHandle) {
+            clearTimeout(state.retryHandle);
+            state.retryHandle = null;
+        }
+        if (!keepAttempts) {
+            this._treeRetryState.delete(networkId);
+        }
+    }
+
+    /**
+     * Receives a 4xx/5xx C-Gate command error and, if it indicates that an
+     * in-flight TreeXML request failed because the network isn't loaded yet,
+     * fast-fails the head of the pending queue and schedules a retry.
+     *
+     * Tree-related "Network not found" errors come back without a path
+     * ("401 Bad object or device ID: Network not found"), whereas getall errors
+     * include a path ("401 Bad object or device ID: //PROJECT/254/56/* (...)").
+     * That difference lets us distinguish the two.
+     */
+    handleCommandError(code, statusData) {
+        if (code !== '401') return;
+        const data = statusData || '';
+        if (!/Network not found/i.test(data)) return;
+        if (/\/\/[^/]+\/\d+/.test(data)) return;
+        if (this.pendingTreeNetworks.length === 0) return;
+
+        const failedNetwork = this.pendingTreeNetworks.shift();
+        this._cancelTreeWatchdog(failedNetwork);
+        this._handleTreeRequestFailure(failedNetwork, '401 Network not found');
+    }
+
+    _handleTreeRequestFailure(networkId, reason) {
+        const state = this._treeRetryState.get(networkId) || { attempts: 0, retryHandle: null };
+        state.attempts += 1;
+
+        if (state.attempts > this._maxTreeRetryAttempts) {
+            this.logger.warn(
+                `HA Discovery: TreeXML for network ${networkId} failed after ${this._maxTreeRetryAttempts} attempts (${reason}). ` +
+                `Auto-discovery for this network is paused. ` +
+                `Verify the network is configured and reachable in C-Gate, then restart the bridge or publish to cbus/write/${networkId}///gettree to retry.`
+            );
+            this._treeRetryState.delete(networkId);
+            return;
+        }
+
+        const delay = Math.min(
+            this._treeRetryInitialDelayMs * Math.pow(2, state.attempts - 1),
+            this._treeRetryMaxDelayMs
+        );
+
+        this.logger.warn(
+            `HA Discovery: TreeXML for network ${networkId} failed (${reason}). ` +
+            `Retrying in ${Math.round(delay / 1000)}s (attempt ${state.attempts}/${this._maxTreeRetryAttempts}). ` +
+            `This typically means C-Gate is still loading networks at startup.`
+        );
+
+        if (state.retryHandle) clearTimeout(state.retryHandle);
+        state.retryHandle = setTimeout(() => {
+            state.retryHandle = null;
+            this.queueTreeRequest(networkId);
+        }, delay);
+        if (typeof state.retryHandle.unref === 'function') state.retryHandle.unref();
+        this._treeRetryState.set(networkId, state);
+    }
+
+    /**
+     * Cancels all retry timers and watchdogs. Call on bridge shutdown.
+     */
+    stop() {
+        for (const handle of this._treeWatchdogs.values()) {
+            clearTimeout(handle);
+        }
+        this._treeWatchdogs.clear();
+        for (const state of this._treeRetryState.values()) {
+            if (state.retryHandle) clearTimeout(state.retryHandle);
+        }
+        this._treeRetryState.clear();
+    }
+
     handleTreeStart(_statusData) {
         if (this.activeTreeSession && this.activeTreeSession.bufferParts.length > 0) {
             this.logger.warn(`Received a new TreeXML start before previous tree completed; dropping incomplete tree for network ${this.activeTreeSession.network}`);
         }
 
         const nextNetwork = this.pendingTreeNetworks.shift() || this.treeNetwork || 'unknown';
+        const networkKey = String(nextNetwork);
+
+        // The request succeeded — cancel watchdog and any pending retry so a
+        // late retry doesn't issue a redundant TREEXML.
+        this._cancelTreeWatchdog(networkKey);
+        this._cancelTreeRetry(networkKey);
+
         this.activeTreeSession = {
-            network: String(nextNetwork),
+            network: networkKey,
             bufferParts: []
         };
 

tests/haDiscovery.test.js

@@ -524,16 +524,160 @@ describe('HaDiscovery', () => {
     describe('Integration with CgateWebBridge', () => {
         it('should handle tree responses from C-Gate correctly', () => {
             haDiscovery.treeNetwork = '254';
-            
+
             haDiscovery.handleTreeStart('start');
             expect(haDiscovery.treeBufferParts).toEqual([]);
-            
+
             haDiscovery.handleTreeData('data1');
             haDiscovery.handleTreeData('data2');
             expect(haDiscovery.treeBufferParts).toEqual(['data1', 'data2']);
         });
     });
 
+    describe('TreeXML retry on startup race (401 Network not found)', () => {
+        beforeEach(() => {
+            jest.useFakeTimers();
+            mockSettings.ha_discovery_networks = ['254'];
+        });
+
+        afterEach(() => {
+            haDiscovery.stop();
+            jest.useRealTimers();
+        });
+
+        it('schedules a retry after a 401 Network not found error for an in-flight TreeXML', () => {
+            haDiscovery.trigger();
+            expect(mockSendCommandFn).toHaveBeenCalledTimes(1);
+            expect(haDiscovery.pendingTreeNetworks).toEqual(['254']);
+
+            haDiscovery.handleCommandError('401', 'Bad object or device ID: Network not found');
+
+            // Failed entry removed from pending so a late tree-start can't be misattributed.
+            expect(haDiscovery.pendingTreeNetworks).toEqual([]);
+            // No retry yet — it's scheduled.
+            expect(mockSendCommandFn).toHaveBeenCalledTimes(1);
+
+            // First retry runs after the initial backoff (2s).
+            jest.advanceTimersByTime(2000);
+            expect(mockSendCommandFn).toHaveBeenCalledTimes(2);
+            expect(haDiscovery.pendingTreeNetworks).toEqual(['254']);
+        });
+
+        it('ignores 401 errors that include a path (not a tree request)', () => {
+            haDiscovery.trigger();
+            haDiscovery.handleCommandError('401', 'Bad object or device ID: //PROJECT/254/56/* (Network not found)');
+            expect(haDiscovery.pendingTreeNetworks).toEqual(['254']);
+            jest.advanceTimersByTime(2000);
+            expect(mockSendCommandFn).toHaveBeenCalledTimes(1);
+        });
+
+        it('ignores 401 errors when no TreeXML is in flight', () => {
+            haDiscovery.handleCommandError('401', 'Bad object or device ID: Network not found');
+            jest.advanceTimersByTime(60000);
+            expect(mockSendCommandFn).not.toHaveBeenCalled();
+        });
+
+        it('uses exponential backoff between successive retries', () => {
+            haDiscovery.trigger();
+            const errMsg = 'Bad object or device ID: Network not found';
+
+            haDiscovery.handleCommandError('401', errMsg); // attempt 1, retry in 2s
+            jest.advanceTimersByTime(2000);
+            expect(mockSendCommandFn).toHaveBeenCalledTimes(2);
+
+            haDiscovery.handleCommandError('401', errMsg); // attempt 2, retry in 4s
+            jest.advanceTimersByTime(3999);
+            expect(mockSendCommandFn).toHaveBeenCalledTimes(2);
+            jest.advanceTimersByTime(1);
+            expect(mockSendCommandFn).toHaveBeenCalledTimes(3);
+
+            haDiscovery.handleCommandError('401', errMsg); // attempt 3, retry in 8s
+            jest.advanceTimersByTime(8000);
+            expect(mockSendCommandFn).toHaveBeenCalledTimes(4);
+        });
+
+        it('gives up after the maximum number of attempts', () => {
+            const warnSpy = jest.spyOn(haDiscovery.logger, 'warn');
+            haDiscovery.trigger();
+            const errMsg = 'Bad object or device ID: Network not found';
+
+            // 8 retries permitted; the 9th failure exhausts the budget.
+            for (let i = 1; i <= 8; i++) {
+                haDiscovery.handleCommandError('401', errMsg);
+                jest.runOnlyPendingTimers();
+            }
+            haDiscovery.handleCommandError('401', errMsg);
+
+            // No further retry scheduled.
+            const callsAfterFinalFailure = mockSendCommandFn.mock.calls.length;
+            jest.advanceTimersByTime(120000);
+            expect(mockSendCommandFn).toHaveBeenCalledTimes(callsAfterFinalFailure);
+            expect(warnSpy.mock.calls.some(([msg]) => /failed after 8 attempts/i.test(msg))).toBe(true);
+        });
+
+        it('falls back to the watchdog when no response arrives within the request timeout', () => {
+            haDiscovery.trigger();
+            expect(mockSendCommandFn).toHaveBeenCalledTimes(1);
+
+            // Watchdog fires after 8s (request timeout), then 2s backoff before retry.
+            jest.advanceTimersByTime(8000);
+            jest.advanceTimersByTime(2000);
+            expect(mockSendCommandFn).toHaveBeenCalledTimes(2);
+        });
+
+        it('cancels pending retry when the next TreeXML succeeds', () => {
+            haDiscovery.trigger();
+            haDiscovery.handleCommandError('401', 'Bad object or device ID: Network not found');
+            jest.advanceTimersByTime(2000);
+
+            // Retry sent — simulate a successful tree response.
+            haDiscovery.handleTreeStart('start');
+            haDiscovery.handleTreeData('<xml/>');
+            jest.spyOn(require('xml2js'), 'parseString').mockImplementation((xml, _opts, cb) => cb(null, {}));
+            haDiscovery.handleTreeEnd('end');
+
+            // Watchdog and retry state should now be cleared.
+            expect(haDiscovery._treeWatchdogs.size).toBe(0);
+            expect(haDiscovery._treeRetryState.size).toBe(0);
+
+            // Advance time well past any potential retry — no extra commands.
+            const callsBefore = mockSendCommandFn.mock.calls.length;
+            jest.advanceTimersByTime(120000);
+            expect(mockSendCommandFn).toHaveBeenCalledTimes(callsBefore);
+        });
+
+        it('retries each network independently when multiple fail', () => {
+            mockSettings.ha_discovery_networks = ['254', '200'];
+            haDiscovery.trigger();
+            expect(mockSendCommandFn).toHaveBeenCalledTimes(2);
+            expect(haDiscovery.pendingTreeNetworks).toEqual(['254', '200']);
+
+            // First 401 is for 254 (FIFO).
+            haDiscovery.handleCommandError('401', 'Bad object or device ID: Network not found');
+            // Second 401 is for 200.
+            haDiscovery.handleCommandError('401', 'Bad object or device ID: Network not found');
+            expect(haDiscovery.pendingTreeNetworks).toEqual([]);
+
+            jest.advanceTimersByTime(2000);
+            expect(mockSendCommandFn).toHaveBeenCalledTimes(4);
+            expect(haDiscovery.pendingTreeNetworks).toEqual(expect.arrayContaining(['254', '200']));
+        });
+
+        it('stop() clears all retry timers and watchdogs', () => {
+            haDiscovery.trigger();
+            haDiscovery.handleCommandError('401', 'Bad object or device ID: Network not found');
+            expect(haDiscovery._treeRetryState.size).toBe(1);
+
+            haDiscovery.stop();
+            expect(haDiscovery._treeWatchdogs.size).toBe(0);
+            expect(haDiscovery._treeRetryState.size).toBe(0);
+
+            const callsBefore = mockSendCommandFn.mock.calls.length;
+            jest.advanceTimersByTime(120000);
+            expect(mockSendCommandFn).toHaveBeenCalledTimes(callsBefore);
+        });
+    });
+
     describe('Custom Label Override (three-tier priority)', () => {
         beforeEach(() => {
             jest.spyOn(require('xml2js'), 'parseString').mockImplementation((xml, _opts, callback) => {