ruvnet/ruflo · error · Error

flywheel anchor manifest requires path and sha256

Error message

flywheel anchor manifest requires path and sha256

What it means

Thrown after the manifest schema check passes, when manifest.path or manifest.sha256 is missing or not a string. Both fields are mandatory: path locates the tasks JSON (relative to the manifest or to the project root) and sha256 is the pinned hash that toSelection() will verify. A manifest with only one of the two is treated as malformed because the integrity pin would be incomplete.

Source

Thrown at v3/@claude-flow/cli/src/services/harness-project-anchor.ts:162

  if (!!options.anchorPath !== !!options.anchorHash) {
    throw new Error('anchorPath and anchorHash must be supplied together');
  }
  if (options.anchorPath && options.anchorHash) {
    return toSelection(containedPath(root, options.anchorPath), options.anchorHash);
  }

  const manifestCandidate = options.manifestPath ?? DEFAULT_PROJECT_ANCHOR_MANIFEST;
  const manifestPath = isAbsolute(manifestCandidate)
    ? manifestCandidate
    : resolve(root, manifestCandidate);
  if (existsSync(manifestPath)) {
    const containedManifest = containedPath(root, manifestPath);
    const manifest = JSON.parse(readFileSync(containedManifest, 'utf8')) as ProjectAnchorManifest;
    if (manifest.schemaVersion !== PROJECT_ANCHOR_MANIFEST_SCHEMA) {
      throw new Error(`unsupported flywheel anchor manifest schema: ${manifest.schemaVersion}`);
    }
    if (typeof manifest.path !== 'string' || typeof manifest.sha256 !== 'string') {
      throw new Error('flywheel anchor manifest requires path and sha256');
    }
    // Manifest-relative paths are easier to relocate while remaining
    // repository-contained; project-relative paths remain supported.
    const manifestRelative = resolve(dirname(containedManifest), manifest.path);
    const requested = existsSync(manifestRelative) ? manifestRelative : resolve(root, manifest.path);
    return toSelection(containedPath(root, requested), manifest.sha256);
  }

  if (isRufloRepository(root) || process.env.RUFLO_FLYWHEEL_ALLOW_BUILTIN_ANCHOR === '1') {
    const frozen = loadFrozenHumanEval();
    return {
      version: frozen.version,
      anchorRef: FROZEN_HUMAN_EVAL_HASH,
      source: 'ruflo-built-in',
      tasks: frozen.tasks.map((task) => ({
        id: task.id,
        input: { id: task.id, q: task.q },
        expected: task.labels,

View on GitHub (pinned to 6b01dc5a68)

Solutions

Ensure both "path" and "sha256" are present and are non-empty strings.
Compute the sha256 over the referenced tasks file (via humanEvalHash) and paste it in.
Validate the manifest shape with a JSON-schema or hand check before pointing the harness at it.

Example fix

// before
{ "schemaVersion": "ruflo.flywheel-anchor-manifest/v1", "path": "tasks.json" }
// after
{ "schemaVersion": "ruflo.flywheel-anchor-manifest/v1", "path": "tasks.json", "sha256": "sha256:abc123..." }

Defensive patterns

Strategy: validation

Validate before calling

function assertManifestFields(path: string): void {
  const m = JSON.parse(readFileSync(path, 'utf8'));
  if (typeof m.path !== 'string' || typeof m.sha256 !== 'string') {
    throw new Error('manifest requires string path and sha256');
  }
}

Type guard

function isCompleteManifest(m: unknown): m is { schemaVersion: string; path: string; sha256: string } {
  return typeof m === 'object' && m !== null
    && typeof (m as { path?: unknown }).path === 'string'
    && typeof (m as { sha256?: unknown }).sha256 === 'string';
}

Try / catch

try {
  loadEffectiveFlywheelAnchor(root, opts);
} catch (e) {
  if (e instanceof Error && /manifest requires path and sha256/.test(e.message)) {
    // add the missing string field(s) to the manifest, then retry
  }
  throw e;
}

Prevention

Always pair path with a freshly-computed sha256 when writing the manifest.
Use the exact key names 'path' and 'sha256'.
Add a generator test asserting both fields are non-empty strings.

When it happens

Trigger: A manifest JSON where path or sha256 is absent, null, a number, or an empty string; a key typo like "file" instead of "path" or "hash" instead of "sha256"; a partially-written manifest from a crashed generator.

Common situations: Authoring the manifest by hand and omitting sha256 because the hash wasn't computed yet; renaming keys to friendlier names; a templating system that left one field as null when the value was unavailable.

Related errors

AI-assisted analysis of ruvnet/ruflo@6b01dc5a68 (2026-08-12). Data as JSON: /api/errors/3a5028ce8516f3f7. Report an issue: GitHub.