What causes "--vector must be a JSON array of numbers, got: ${raw}" in ruvnet/ruflo?

Pass a flat JSON array of numbers, e.g. --vector '[0.1, 0.2, 0.3]'

ruvnet/ruflo · error · Error

--vector must be a JSON array of numbers, got: ${raw}

Error message

--vector must be a JSON array of numbers, got: ${raw}

What it means

Validates the --vector CLI flag: the string must parse as JSON and the result must be an array whose every element is a number. Note the ordering — malformed JSON makes JSON.parse itself throw SyntaxError first; this specific message fires when the JSON is syntactically valid but not a flat number[] (an object, or an array containing strings, nulls, booleans, or nested arrays).

Source

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

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',
      description: 'Initialize IoT Cognitum plugin configuration',
      options: [
        { name: 'fleet-id', description: 'Default fleet identifier', type: 'string', default: 'default' },
        { name: 'zone-id', description: 'Default IEC 62443 security zone', type: 'string', default: 'zone-0' },
        { name: 'insecure', description: 'Allow TLS-insecure connections', type: 'boolean', default: true },
      ],
      handler: async (args) => {

View on GitHub (pinned to fa13ee4ad6)

Solutions

Pass a flat JSON array of numbers, e.g. --vector '[0.1, 0.2, 0.3]'
Quote the argument in the shell so brackets and quotes survive intact
Replace strings, nulls, and nested arrays with plain numbers (null/NaN placeholders are not accepted)

Example fix

# before
$ iot ingest --device-id seed-42 --vector '[0.1, null, "0.3"]'
# Error: --vector must be a JSON array of numbers

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

Defensive patterns

Strategy: validation

Validate before calling

const parsed: unknown = JSON.parse(raw);
if (!isNumberArray(parsed)) {
  throw new Error(`--vector must be a flat JSON array of numbers, got: ${raw}`);
}
spawnSync('iot', ['ingest', '--device-id', deviceId, '--vector', JSON.stringify(parsed)]);

Type guard

function isNumberArray(v: unknown): v is number[] {
  return Array.isArray(v) && v.every((n) => typeof n === 'number' && Number.isFinite(n));
}

Try / catch

try {
  const vector = parseVectorCli(raw);
} catch (e) {
  if (e instanceof Error && e.message.startsWith('--vector must be a JSON array')) {
    // sanitize the data or re-prompt; do not re-submit the same string
  } else throw e;
}

Prevention

Build CLI arguments programmatically with JSON.stringify instead of string concatenation
Sanitize sensor data (drop nulls, coerce numeric strings) before building the vector
Single-quote JSON arguments in POSIX shells so quoting survives

When it happens

Trigger: Passing --vector '{"values":[1]}' (object, not array), '[1,"2"]', '[1,null]', '[[1,2]]', or any valid-JSON shape that is not a flat array of numbers.

Common situations: Shell quoting that mangles the JSON; hand-written vectors using strings or null placeholders for missing sensor values; attempting the metadata-object form that only the stdin channel accepts.

Related errors

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