ruvnet/ruflo · error · Error

IoT Cognitum not initialized. Run "iot register" first.

Error message

IoT Cognitum not initialized. Run "iot register" first.

What it means

CLI-level precondition guard for the IoT Cognitum plugin: operational iot commands obtain the coordinator through requireCoordinator(get), which throws when the plugin's IoTCoordinator is null — IoT Cognitum was never initialized in this project. The message names the remedy: run iot register first.

Source

Thrown at v3/@claude-flow/plugin-iot-cognitum/src/cli-commands.ts:10

import type { CLICommandDefinition, PluginContext } from '@claude-flow/shared/src/plugin-interface.js';
import type { IoTCoordinator } from './application/iot-coordinator.js';
import { getDeviceTrustLabel } from './domain/entities/device-trust-level.js';

type CoordinatorGetter = () => IoTCoordinator | null;
type ContextGetter = () => PluginContext | null;

function requireCoordinator(get: CoordinatorGetter): IoTCoordinator {
  const c = get();
  if (!c) throw new Error('IoT Cognitum not initialized. Run "iot register" first.');
  return c;
}

function parseVector(raw: string): number[] {
  const parsed = JSON.parse(raw) as unknown;
  if (!Array.isArray(parsed) || !parsed.every((n) => typeof n === 'number')) {
    throw new Error(`--vector must be a JSON array of numbers, got: ${raw}`);
  }
  return parsed as number[];
}

export function createCliCommands(
  getCoordinator: CoordinatorGetter,
  _getContext: ContextGetter,
): CLICommandDefinition[] {
  return [
    {
      name: 'iot init',

View on GitHub (pinned to fa13ee4ad6)

Solutions

Run `iot register` (after `iot init` if not yet configured) and re-run the command
Verify the IoT plugin is loaded and healthy via plugin status or init output
Run the CLI in the project directory where the IoT state was created

Example fix

# before
$ iot ingest --device-id seed-42 --vector '[0.1,0.2]'
# Error: IoT Cognitum not initialized. Run "iot register" first.

# after
$ iot register
$ iot ingest --device-id seed-42 --vector '[0.1,0.2]'

Defensive patterns

Strategy: validation

Validate before calling

#!/usr/bin/env bash
iot init
iot register || exit 1
iot ingest --device-id seed-42 --vector '[0.1,0.2]'

Try / catch

try {
  await runCli(['iot', 'ingest', ...args]);
} catch (e) {
  if (e instanceof Error && e.message.includes('IoT Cognitum not initialized')) {
    await runCli(['iot', 'register']); // one-time bootstrap, then retry
  } else throw e;
}

Prevention

Make `iot init` plus `iot register` the first commands of any IoT automation script
Run iot commands from the project directory that owns the IoT state
Check plugin load status after upgrades before invoking iot commands

When it happens

Trigger: Running any operational iot command (ingest, mesh, fleet/device commands) before the one-time iot init plus iot register setup completed successfully in the same working directory.

Common situations: Fresh clone or new machine without IoT state; the plugin failed to load at startup; running the CLI from a different directory so the per-project state is not found; init step skipped in automation scripts.

Related errors

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