affaan-m/ECC · error · Error

${harness.label} is an advanced harness and is not guided-re

Error message

${harness.label} is an advanced harness and is not guided-ready

What it means

Thrown by normalizeHarnessSelection() when a token resolves to a real harness capability but that harness has guidedReady === false. Guided install only accepts harnesses flagged guided-ready; advanced harnesses require a different install path.

Source

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

    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,
  listGuidedHarnesses,
  listHarnessCapabilities,
  normalizeHarnessSelection,

View on GitHub (pinned to 01e15490f0)

Solutions

Pick a guided-ready harness instead: 'claude', 'codex', or 'kimi'.
If you really want an advanced harness, use the component install path (install.sh --target <id> --profile full) rather than the guided selector.
Filter the visible menu to listGuidedHarnesses() only.

Example fix

// before
normalizeHarnessSelection('cursor');

// after (guided path)
normalizeHarnessSelection('claude');
// or (advanced path, bypass guided selector)
// install.sh --target cursor --profile full

Defensive patterns

Strategy: validation

Validate before calling

const { listHarnessCapabilities } = require('./harness-capabilities');
function isGuidedToken(token) {
  const h = listHarnessCapabilities().find(h =>
    [h.id, h.label, ...h.aliases].map(s => s.toLowerCase()).includes(token.trim().toLowerCase()));
  return Boolean(h && h.guidedReady);
}
if (!isGuidedToken(token)) {
  throw new Error(`${token} is not guided-ready; use install.sh --target ${token} --profile full`);
}

Type guard

function isGuidedHarness(v) {
  return v != null && typeof v === 'object' && v.guidedReady === true;
}

Try / catch

try {
  return normalizeHarnessSelection(sel);
} catch (err) {
  if (/not guided-ready/.test(err.message)) {
    console.error(`${err.message}\nUse: install.sh --target <id> --profile full`);
  }
  throw err;
}

Prevention

Filter the interactive menu to listGuidedHarnesses() only.
Document which harnesses are guided-ready vs advanced in the install guide.
In config, validate guided-ready status before forwarding to the selector.

When it happens

Trigger: Token maps to a HARNESS_CAPABILITIES entry with guidedReady: false (cursor, antigravity, gemini, opencode, codebuddy, joycode, qwen, zed, hermes, openclaw) inside the normalizeHarnessSelection loop.

Common situations: User runs the guided installer and types 'cursor' or 'opencode'; menu shows advanced harnesses and user picks one by name; config file lists an advanced harness under the guided selection.

Related errors

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