affaan-m/ECC · error · Error

Unknown guided harness selection: ${token}

Error message

Unknown guided harness selection: ${token}

What it means

Thrown by normalizeHarnessSelection() when a token cannot be resolved to any harness via getHarnessCapability or numeric menu index. The token is echoed verbatim so the user can see what failed.

Source

Thrown at scripts/lib/harness-capabilities.js:338

  const allTokens = tokens.filter(token => ['all', '*'].includes(normalizeLookupToken(token)));
  const explicitTokens = tokens.filter(token => !['all', '*'].includes(normalizeLookupToken(token)));
  if (allTokens.length > 0 && explicitTokens.length > 0) {
    throw new Error('The all/* harness selection cannot be combined with other selections');
  }
  if (allTokens.length > 0) {
    return GUIDED_HARNESS_IDS.slice();
  }

  const selected = new Set();
  for (const token of tokens) {
    const normalizedToken = normalizeLookupToken(token);
    const menuIndex = /^\d+$/.test(normalizedToken) ? Number(normalizedToken) - 1 : -1;
    const harness = menuIndex >= 0
      ? listGuidedHarnesses()[menuIndex] || null
      : getHarnessCapability(token);

    if (!harness) {
      throw new Error(`Unknown guided harness selection: ${token}`);
    }
    if (!harness.guidedReady) {
      throw new Error(`${harness.label} is an advanced harness and is not guided-ready`);
    }
    selected.add(harness.id);
  }

  if (selected.size === 0) {
    throw new Error('At least one guided harness must be selected');
  }

  return GUIDED_HARNESS_IDS.filter(id => selected.has(id));
}

module.exports = {
  GUIDED_HARNESS_IDS,
  HARNESS_CAPABILITIES,
  getHarnessCapability,

View on GitHub (pinned to 01e15490f0)

Solutions

1. List valid harnesses: console.log(require('./harness-capabilities').listHarnessCapabilities().map(h => h.id)).
2. Correct the typo (e.g. 'claud' -> 'claude'); remember aliases like 'claude-code' are accepted.
3. Use a numeric menu index from listGuidedHarnesses() (1-based).
4. Strip stray whitespace and unicode look-alikes from the token.

Example fix

// before
normalizeHarnessSelection('claud,codex');

// after
normalizeHarnessSelection('claude,codex');

const { listHarnessCapabilities } = require('./harness-capabilities');
const known = new Set(listHarnessCapabilities().flatMap(h => [h.id, h.label, ...h.aliases]));
function isKnownToken(token) {
  return known.has(token) || /^\d+$/.test(String(token).trim());
}
if (!tokens.every(isKnownToken)) {
  throw new Error(`Unknown harness token. Valid: ${[...known].join(', ')}`);
}

function isHarnessToken(v) {
  if (typeof v !== 'string') return false;
  const t = v.trim().toLowerCase();
  return t === 'all' || t === '*' || /^\d+$/.test(t)
    || listHarnessCapabilities().some(h =>
      [h.id, h.label, ...h.aliases].map(s => s.toLowerCase()).includes(t));
}

try {
  return normalizeHarnessSelection(sel);
} catch (err) {
  if (/Unknown guided harness/.test(err.message)) {
    throw new Error(`${err.message}. Valid guided: claude, codex, kimi`);
  }
  throw err;
}

When it happens

Trigger: For each token, getHarnessCapability(token) returns null and it is not a numeric menu index that maps into listGuidedHarnesses(). Happens with typos like 'claud', unregistered harnesses like 'copilot', or tokens with stray punctuation.

Common situations: Typo in harness id on CLI; user assumes a harness exists (e.g. 'copilot', 'aider') that ECC does not ship; outdated docs reference a renamed harness; token has invisible whitespace or unicode dash.

Related errors

• At least one guided harness must be selected
• The all/* harness selection cannot be combined with other se
• Refusing to run install from untrusted repo root ${normalize
• Unknown argument: ${arg}
• Invalid repo: ${repo}

AI-assisted analysis of affaan-m/ECC@01e15490f0 (2026-08-13). Data as JSON: /api/errors/ad9364d94c93b820. Report an issue: GitHub.