ruvnet/RuView · error · RangeError

unsupported guidance topic: ${topic}

Error message

unsupported guidance topic: ${topic}

What it means

getGuidance validates input.topic against the frozen GUIDANCE_TOPICS allowlist (guidance.js:12): overview, architecture, sensing, hardware, training, homecore, integrations, deployment, community, testing. Matching is exact and case-sensitive; anything else throws this RangeError with the offending topic embedded.

Source

Thrown at harness/ruview/src/guidance.js:361

  }
  if (!options || typeof options !== 'object' || Array.isArray(options)) {
    throw new TypeError('guidance options must be an object');
  }
  if (input.topic !== undefined && typeof input.topic !== 'string') {
    throw new TypeError('guidance topic must be a string');
  }
  if (input.query !== undefined && typeof input.query !== 'string') {
    throw new TypeError('guidance query must be a string');
  }
  if (input.limit !== undefined && (typeof input.limit !== 'number' || !Number.isFinite(input.limit))) {
    throw new TypeError('guidance limit must be a finite number');
  }
  if (options.repoRoot !== undefined && options.repoRoot !== null && typeof options.repoRoot !== 'string') {
    throw new TypeError('guidance repoRoot must be a string or null');
  }
  const topic = input.topic === undefined ? 'overview' : input.topic;
  if (!GUIDANCE_TOPICS.includes(topic)) {
    throw new RangeError(`unsupported guidance topic: ${topic}`);
  }
  const query = input.query === undefined ? '' : input.query.trim();
  if (query && (query.length < 2 || query.length > 500)) {
    throw new RangeError('guidance query must contain 2..500 characters');
  }
  const rawLimit = input.limit === undefined ? 20 : input.limit;
  if (!Number.isFinite(rawLimit) || rawLimit < 1 || rawLimit > 20) {
    throw new RangeError('guidance limit must be between 1 and 20');
  }
  const limit = Math.floor(rawLimit);
  const wanted = tokenize(query);
  const candidates = CAPABILITIES
    .filter((capability) => topic === 'overview' || capability.topics.includes(topic))
    .map((capability, order) => ({ capability, order, score: scoreCapability(capability, wanted) }))
    .filter(({ score }) => score > 0)
    .sort((a, b) => b.score - a.score || a.order - b.order)
    .slice(0, limit)
    .map(({ capability }) => ({

View on GitHub (pinned to 4685618388)

Solutions

1. Use one of the exact allowlisted topics; for the Homecore metaharness questions like plugins/restore use topic 'homecore' with a query.
2. Import and check the list before calling: import { GUIDANCE_TOPICS } from the guidance module; if (!GUIDANCE_TOPICS.includes(topic)) topic = 'overview';
3. Lowercase and trim caller input before validation: topic: String(raw).trim().toLowerCase().

Example fix

// before
getGuidance({ topic: 'plugins' }) // RangeError: unsupported guidance topic: plugins
// after
import { GUIDANCE_TOPICS } from './src/guidance.js';
const topic = GUIDANCE_TOPICS.includes(rawTopic) ? rawTopic : 'overview';
getGuidance({ topic });

import { GUIDANCE_TOPICS } from '@ruvnet/ruview/src/guidance.js';
const topic = String(rawTopic ?? 'overview').trim().toLowerCase();
if (!GUIDANCE_TOPICS.includes(topic)) {
  throw new Error(`unsupported topic '${topic}'; valid: ${GUIDANCE_TOPICS.join(', ')}`);
}
getGuidance({ topic });

import { GUIDANCE_TOPICS } from '@ruvnet/ruview/src/guidance.js';
function isGuidanceTopic(v) {
  return typeof v === 'string' && GUIDANCE_TOPICS.includes(v);
}

try {
  getGuidance({ topic });
} catch (e) {
  if (e instanceof RangeError && e.message.startsWith('unsupported guidance topic')) {
    return getGuidance({ topic: 'overview' }); // sensible fallback topic
  }
  throw e;
}

When it happens

Trigger: getGuidance({ topic: 'plugins' }) (a homecore-harness topic, not a ruview topic), { topic: 'home core' }, { topic: 'Overview' } (capital O), { topic: 'restore' }, or a typo like 'comunity'.

Common situations: Confusing the ruview guidance topics with homecore guidance topics (plugins/restore are homecore); copying a topic from one harness CLI to the other; casing changes after a rename.

Related errors

• guidance query must contain 2..500 characters
• guidance limit must be between 1 and 20
• guidance input must be an object
• guidance options must be an object
• guidance topic must be a string

AI-assisted analysis of ruvnet/RuView@4685618388 (2026-08-16). Data as JSON: /api/errors/4dfd35b4946b20d6. Report an issue: GitHub.