ruvnet/ruflo · error · Error

Device ${deviceId} not registered with coordinator

Error message

Device ${deviceId} not registered with coordinator

What it means

Internal guard in IoTCoordinator: resolveClient()/requireEntry() look a device up in the coordinator's devices map and throw when it is absent, meaning the device was never registered with this coordinator (or its registration no longer exists in this instance). Every coordinator operation that needs the Seed client funnels through it.

Source

Thrown at v3/@claude-flow/plugin-iot-cognitum/src/application/iot-coordinator.ts:578

  // -------------------------------------------------------------------------
  // Internals
  // -------------------------------------------------------------------------

  /**
   * Resolve a SeedClient by device ID (or temporary endpoint key).
   * Throws when the device has not been registered.
   */
  private resolveClient(deviceId: string): SeedClient {
    return this.requireEntry(deviceId).client;
  }

  private requireEntry(
    deviceId: string,
  ): { agent: DeviceAgent; client: SeedClient } {
    const entry = this.devices.get(deviceId);
    if (!entry) {
      throw new Error(`Device ${deviceId} not registered with coordinator`);
    }
    return entry;
  }
}

View on GitHub (pinned to fa13ee4ad6)

Solutions

1. Register the device first (the iot register CLI flow or the registration API) and confirm it appears in the registry
2. Double-check the device-id string for typos or stale values
3. If the coordinator restarted and the registry is not persisted, re-register devices before resuming operations

Example fix

// before
await coordinator.ingestDeviceTelemetry('seed-42', vectors); // seed-42 never registered

// after
await coordinator.registerDevice('seed-42', endpoint); // or run `iot register`
await coordinator.ingestDeviceTelemetry('seed-42', vectors);

const registered = new Set<string>(loadRegisteredDeviceIds());
if (!registered.has(deviceId)) {
  throw new Error(`device ${deviceId} unknown to this coordinator; register it first`);
}
await coordinator.ingestDeviceTelemetry(deviceId, vectors);

try {
  await coordinator.ingestDeviceTelemetry(deviceId, vectors);
} catch (e) {
  if (e instanceof Error && e.message.endsWith('not registered with coordinator')) {
    await registerDevice(deviceId);
    await coordinator.ingestDeviceTelemetry(deviceId, vectors); // retry once
  } else throw e;
}

When it happens

Trigger: Calling coordinator operations (telemetry ingest, mesh topology, lifecycle actions) with a device-id that was never registered via the registration flow, was unregistered, or whose registration was lost because the coordinator's in-memory registry did not survive a restart.

Common situations: Running ingest or mesh commands right after coordinator startup before re-registering devices; a typo'd device ID; a device registered against a different coordinator instance; tests sharing coordinator state incorrectly.

Related errors

• IoT Cognitum not initialized
• Issue ${input.issueId} is not stealable or not claimed
• Store not initialized. Call initialize() first.
• refusing to prepare writing worktrees from a dirty repositor
• Federation not initialized

AI-assisted analysis of ruvnet/ruflo@fa13ee4ad6 (2026-08-18). Data as JSON: /api/errors/84d9cb91ea634b7a. Report an issue: GitHub.