ruvnet/ruflo · error · Error

label exceeds 256 chars

Error message

label exceeds 256 chars

What it means

Thrown by validateLabel() (agenticow-loader.ts:89) when a branch/checkpoint label is longer than 256 characters. The label is stored in the lineage manifest and used in branchPath lookups, so the loader caps it to keep manifest entries and log output bounded.

Source

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

  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 = {};
  if (typeof dimension === 'number' && Number.isInteger(dimension) && dimension > 0) {

View on GitHub (pinned to fa13ee4ad6)

Solutions

1. Shorten the label to a human-meaningful slug under 256 chars ('run-2026-08-18-fix-auth')
2. Keep long data out of labels — records carry an optional numeric id and text field for payload
3. Truncate generated labels explicitly: label.slice(0, 256)

Example fix

// before
const label = `candidate-${JSON.stringify(taskContext)}-${crypto.randomUUID()}`; // way over 256 chars
await callTool('agenticow_branch', { path: p, label });

// after
const label = `candidate-${Date.now()}`.slice(0, 64);
await callTool('agenticow_branch', { path: p, label });

const MAX_LABEL = 256;
function fitLabel(label: string): string {
  if (label.length > MAX_LABEL) return label.slice(0, MAX_LABEL);
  return label;
}

try {
  await callTool('agenticow_branch', args);
} catch (e) {
  if (e instanceof Error && e.message === 'label exceeds 256 chars') {
    args.label = args.label.slice(0, 256);
    return callTool('agenticow_branch', args);
  }
  throw e;
}

When it happens

Trigger: Calling agenticow_branch / agenticow_checkpoint / agenticow_rollback / agenticow_promote, or submitting an agenticow_speculate candidate, with a label longer than 256 chars — e.g. a pasted sentence, a UUID-plus-timestamp-plus-hash composite, or a whole task description used as a label.

Common situations: Auto-generated labels that concatenate run metadata without truncation; LLM-driven agents using the task prompt as the label; copying a filename plus path plus description into the label field.

Related errors

• memory path is required
• label is required
• label may only contain [A-Za-z0-9_.\\-:/@]
• records must be a non-empty array of {id?, vector, text?}
• memory path contains disallowed characters

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