ruvnet/ruflo · error · Error

label is required

Error message

label is required

What it means

Thrown by validateLabel() (agenticow-loader.ts:88) when a copy-on-write branch/checkpoint label is falsy (undefined, null, '') or not a string. Labels identify branches and checkpoints in the agenticow COW chain persisted in the <file>.agenticow.json lineage manifest, so an empty label would make lineage entries unaddressable.

Solutions

1. Supply a short non-empty label from the allowed charset [A-Za-z0-9_.\-:/@] (e.g. 'pre-ingest-checkpoint')
2. If generating labels programmatically, default them (e.g. `label: rawLabel || 'branch-' + Date.now()`)
3. Validate the candidates array entries before calling agenticow_speculate

Example fix

// before
await callTool('agenticow_checkpoint', { path: 'memory/main.rvf', label: '' });
// throws: label is required

// after
await callTool('agenticow_checkpoint', { path: 'memory/main.rvf', label: 'before-bulk-ingest' });

function assertLabel(label: unknown): string {
  if (typeof label !== 'string' || label.length === 0) {
    throw new TypeError('label must be a non-empty string');
  }
  return label;
}

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

try {
  await callTool('agenticow_checkpoint', args);
} catch (e) {
  if (e instanceof Error && e.message === 'label is required') {
    args.label = `auto-${Date.now()}`;
    return callTool('agenticow_checkpoint', args);
  }
  throw e;
}

When it happens

Trigger: Calling agenticow_branch, agenticow_checkpoint, agenticow_rollback or agenticow_promote without a label; passing label:'' — note the speculate handler wraps values with String(), so a candidate with label omitted becomes the string 'undefined' and passes, but an explicitly empty string '' throws.

Common situations: Forgetting the label argument when scripting a checkpoint before a risky ingest; a generated label field that came back empty from an upstream system; candidate arrays in agenticow_speculate whose entries were built dynamically and lost their label key.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• memory path is required
• label exceeds 256 chars
• label may only contain [A-Za-z0-9_.\\-:/@]
• records must be a non-empty array of
• at least one candidate is required

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

Appendix: 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 fa13ee4ad6)