affaan-m/ECC · error

is an advanced harness and is not guided-ready

Error message

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

What it means

normalizeHarnessSelection() resolves the token to a harness capability object, then requires harness.guidedReady. Harnesses that exist and are supported but are flagged as advanced (not guided-ready) are rejected for guided workflows with this error. The library deliberately separates 'supported' from 'guided-ready' so guided flows never run against harnesses lacking the automation hooks they assume.

Solutions

1. Pick a guided-ready harness (check guidedReady on entries from listGuidedHarnesses()).
2. If the advanced harness is intentional, use the non-guided workflow/flags instead of the guided API.
3. If the harness should be guided-ready, update its capability definition (guidedReady: true) after verifying it meets guided requirements.

Example fix

// before
normalizeHarnessSelection(['my-advanced-harness']); // throws: not guided-ready
// after
const { listGuidedHarnesses } = require('./scripts/lib/harness-capabilities');
const guidedIds = listGuidedHarnesses().filter(h => h.guidedReady).map(h => h.id);
normalizeHarnessSelection(['my-advanced-harness'].filter(id => guidedIds.includes(id)));

const { getHarnessCapability } = require('./scripts/lib/harness-capabilities');
function isGuidedReady(token) {
  const h = getHarnessCapability(token);
  return h != null && h.guidedReady === true;
}
if (!tokens.every(isGuidedReady)) {
  throw new Error('All harnesses must be guided-ready for guided workflows');
}

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

try {
  const ids = normalizeHarnessSelection(tokens);
} catch (err) {
  if (err.message.includes('is not guided-ready')) {
    console.error(`${err.message} — use the non-guided workflow or choose a guided harness.`);
  } else throw err;
}

When it happens

Trigger: Calling normalizeHarnessSelection (directly or via askHarnesses/normalizedHarnesses/selectedHarnessIds/harnesses/runTests) with a valid, registered harness id or menu number whose capability object has guidedReady === false, e.g. requesting an advanced harness for a guided install/test run.

Common situations: Users selecting a power-user harness by id in a guided script; config files left from manual setups that name an advanced harness; teams whose CI reuses guided entry points with advanced harness ids.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• Unknown guided harness selection
• Agents directory not found
• --all-harnesses and --harness are mutually exclusive.
• all overlays must be readable local files
• all takes must be readable local files

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

Appendix: source

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

    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 8321021c54)