affaan-m/ECC · error · Error

Consult requires a natural language query, for example…

Error message

Consult requires a natural language query, for example: security reviews

What it means

buildConsultation tokenizes options.query and requires at least one meaningful token before ranking components. An empty or whitespace-only query cannot be ranked, so the tool throws with an example of acceptable input. This is a guard against running a consultation with nothing to search for.

Solutions

Pass a natural language query, e.g. `node scripts/consult.js "security reviews"`.
Check flag parsing so positional words are not consumed as flag values (queryParts assembly in parseArgs).
In code, validate query non-empty before calling buildConsultation and prompt the user otherwise.

Example fix

// before
node scripts/consult.js --target skills
// after
node scripts/consult.js --target skills "security reviews"

Defensive patterns

Strategy: validation

Validate before calling

const query = process.argv.slice(2).filter(a => !a.startsWith('--')).join(' ').trim();
if (!query) {
  console.error('Usage: consult <natural language query>');
  process.exit(1);
}

Type guard

function hasQuery(options) { return typeof options?.query === 'string' && options.query.trim().length > 0; }

Try / catch

try {
  buildConsultation(options);
} catch (e) {
  if (/natural language query/.test(e.message)) {
    console.error('A query is required, e.g. consult "security reviews"');
  } else throw e;
}

Prevention

Require a positional query argument in wrapper scripts and error out early with usage text.
Trim and check query before invoking in code.
Show --help when argv contains only flags.

When it happens

Trigger: Calling buildConsultation(options) (or the CLI) where options.query is empty string, whitespace, or missing — e.g. all argv words were consumed as flag values or the user passed only flags.

Common situations: Running `node scripts/consult.js` with no query text; quoting mistakes causing the query to be swallowed by a flag; programmatically passing query: '' after trimming.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

AI-assisted analysis of affaan-m/ECC@8321021c54 (2026-09-16). Data as JSON: /api/errors/783da80523ea145b. Report an issue: GitHub.

Appendix: source

Thrown at scripts/consult.js:397

      };
    })
    .filter(result => result.score > 0)
    .sort((left, right) => right.score - left.score || left.profile.id.localeCompare(right.profile.id))
    .slice(0, Math.min(3, limit))
    .map(result => ({
      id: result.profile.id,
      description: result.profile.description,
      moduleCount: result.profile.moduleCount,
      score: result.score,
      reasons: result.reasons.length > 0 ? result.reasons : ['related install profile'],
      installCommand: commandFor('profile', result.profile.id, target),
    }));
}

function buildConsultation(options) {
  const queryTokens = tokenize(options.query);
  if (queryTokens.length === 0) {
    throw new Error('Consult requires a natural language query, for example: security reviews');
  }

  const matches = rankComponents({
    queryTokens,
    target: options.target,
    limit: options.limit,
  });
  const profiles = rankProfiles({
    queryTokens,
    target: options.target,
    limit: options.limit,
  });

  return {
    schemaVersion: SCHEMA_VERSION,
    query: options.query,
    target: options.target,
    generatedAt: new Date().toISOString(),

View on GitHub (pinned to 8321021c54)