ruvnet/RuView · error · RangeError

guidance query must contain 2..500 characters

Error message

guidance query must contain 2..500 characters

What it means

When a guidance query is supplied, getGuidance trims it and requires the trimmed length to be between 2 and 500 characters inclusive. An empty/whitespace-only query is treated as 'no query' and passes; a 1-character query or one over 500 characters throws this RangeError.

Source

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

  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 }) => ({
      ...capability,
      topics: [...capability.topics],
      sources: [...capability.sources],
      validation: [...capability.validation],

View on GitHub (pinned to 4685618388)

Solutions

1. Trim the query and lengthen or drop it when < 2 chars: const q = raw.trim(); query: q.length >= 2 ? q : undefined.
2. Truncate long queries to the cap: query: q.slice(0, 500).
3. For long context, pass a short keyword query and put details elsewhere — guidance is a keyword navigator, not a search engine.

Example fix

// before
getGuidance({ topic: 'architecture', query: rawPrompt }) // rawPrompt is 900 chars
// after
const q = rawPrompt.trim().slice(0, 500);
getGuidance({ topic: 'architecture', query: q.length >= 2 ? q : undefined });

const q = typeof rawQuery === 'string' ? rawQuery.trim() : '';
const query = q.length >= 2 && q.length <= 500 ? q : undefined;
getGuidance({ query });

function isValidGuidanceQuery(v) {
  if (typeof v !== 'string') return v === undefined;
  const t = v.trim();
  return t === '' || (t.length >= 2 && t.length <= 500);
}

try {
  getGuidance({ query });
} catch (e) {
  if (e instanceof RangeError && e.message.includes('2..500')) {
    return getGuidance({ query: undefined }); // drop the bad query
  }
  throw e;
}

When it happens

Trigger: getGuidance({ query: 'a' }) or { query: ' x' } (trims to 1 char); auto-generated prompts concatenated past 500 chars; passing a long error string or stack trace as the query.

Common situations: Single-character/symbol lookups (e.g. 'v2' is fine at 2 chars, 'v' is not); RAG/agent pipelines that stuff whole documents into the query field; copy-pasted multi-paragraph questions exceeding the cap.

Related errors

• unsupported guidance topic: ${topic}
• 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/90b1ff5754b7e5b9. Report an issue: GitHub.