ruvnet/ruflo · error · Error

label is required

Error message

label is required

What it means

Thrown by validateLabel() in agenticow-loader when the supplied branch/checkpoint label is falsy, not a string, or empty. Labels name COW branches and checkpoints in the agenticow lineage chain; an empty label would collide branches and break the lineage manifest, so it is rejected before any branch handle is opened.

Source

Thrown at v3/@claude-flow/cli/src/mcp-tools/agenticow-loader.ts:88

export function resolveMemoryPath(path: string): string {
  if (!path || typeof path !== 'string') throw new Error('memory path is required');
  if (/\.\.[\\/]|\0/.test(path)) throw new Error('memory path contains disallowed characters');
  return isAbsolute(path) ? path : resolve(getProjectCwd(), path);
}

/**
 * Lineage manifest companion path. agenticow persists the COW chain
 * (working → checkpoints → base) into `<file>.agenticow.json` next to the
 * `.rvf` data file. Without it, forks/checkpoints are in-memory only and
 * disappear when the AgenticMemory handle closes.
 */
export function manifestFor(file: string): string {
  return `${file}.agenticow.json`;
}

/** Validate a COW branch/checkpoint label (alnum + a small safe symbol set). */
export function validateLabel(label: string): string {
  if (!label || typeof label !== 'string') throw new Error('label is required');
  if (label.length > 256) throw new Error('label exceeds 256 chars');
  if (!/^[A-Za-z0-9_.\-:/@]+$/.test(label)) {
    throw new Error('label may only contain [A-Za-z0-9_.\\-:/@]');
  }
  return label;
}

/**
 * Open (or create) a memory file, restoring its COW chain from the lineage
 * manifest when one exists. When neither the `.rvf` nor the manifest exists,
 * `dimension` is required to create a fresh base.
 */
export async function openWithLineage(api: AgenticowApi, file: string, dimension?: number) {
  const manifest = manifestFor(file);
  if (existsSync(manifest)) {
    return (api.AgenticMemory as any).load(manifest);
  }
  const opts: any = {};

View on GitHub (pinned to 6b01dc5a68)

Solutions

1. Always supply a non-empty label for every candidate/branch/checkpoint.
2. Map/rename legacy field names to `label` at your boundary before calling the tool.
3. If generating labels programmatically, fail loudly when the generator returns empty rather than passing it through.

Example fix

// before
speculate({ basePath, candidates: [{ ingest: [...] }] }); // throws
// after
speculate({ basePath, candidates: [{ label: 'exp-a', ingest: [...] }] });

function requireLabel(label: unknown): string {
  if (typeof label !== 'string' || label.length === 0) throw new Error('candidate.label is required');
  return label;
}

const isLabel = (v: unknown): v is string => typeof v === 'string' && v.length > 0 && v.length <= 256;

null

When it happens

Trigger: Calling an agenticow branching tool (fork/checkpoint/speculate) without a label; passing label as undefined/null/''; a candidate object missing its label field; a template that produced an empty string.

Common situations: Candidate list where one entry forgot `label`; integrator assumed label was optional; a refactor that renamed `branchName` to `label` left callers using the old key.

Related errors

• label may only contain [A-Za-z0-9_.\-:/@]
• memory path is required
• dimension is required when creating a new memory file
• at least one candidate is required
• roomLabel is required

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