ruvnet/ruflo · error · Error

Invalid CFP format: expected magic 'CFP1', got '${parsed.mag

Error message

Invalid CFP format: expected magic 'CFP1', got '${parsed.magic}'

What it means

After JSON.parse succeeds, deserializeCFP checks parsed.magic === 'CFP1'. The magic field is the format's version discriminator; anything else — CFP0, CFP2, a missing magic (undefined), or an unrelated JSON document — is rejected with this error showing the value it found. This is a format/version guard, separating 'valid JSON but wrong format' from the JSON syntax failure in the sibling check.

Source

Thrown at v3/@claude-flow/cli/src/transfer/serialization/cfp.ts:153

  }
}

/**
 * Deserialize CFP from string/buffer
 */
export function deserializeCFP(data: string | Buffer): CFPFormat {
  const str = typeof data === 'string' ? data : data.toString('utf-8');

  let parsed: CFPFormat;
  try {
    parsed = JSON.parse(str);
  } catch (e) {
    throw new Error(`Invalid CFP file: ${e instanceof Error ? e.message : String(e)}`);
  }

  // Validate magic bytes
  if (parsed.magic !== 'CFP1') {
    throw new Error(`Invalid CFP format: expected magic 'CFP1', got '${parsed.magic}'`);
  }

  return parsed;
}

/**
 * Validate CFP document
 */
export function validateCFP(cfp: CFPFormat): { valid: boolean; errors: string[] } {
  const errors: string[] = [];

  if (cfp.magic !== 'CFP1') {
    errors.push(`Invalid magic bytes: ${cfp.magic}`);
  }

  if (!cfp.version) {
    errors.push('Missing version');
  }

View on GitHub (pinned to fa13ee4ad6)

Solutions

Confirm the file is a CFP export produced by serializeToJson/serializeToBuffer — check the first bytes contain "magic":"CFP1"
If you are creating fixtures, build them via serializeCFP/serializeToJson instead of hand-writing JSON
A different magic value means a format version this reader does not support — upgrade the package or re-export as CFP1
Verify you passed the right path/CID; ordinary JSON config files will parse but fail this check

Example fix

// before
const cfp = deserializeCFP(await fs.readFile('settings.json')); // -> Invalid CFP format: expected magic 'CFP1', got 'undefined'

// after
const cfp = deserializeCFP(await fs.readFile('pattern.cfp.json')); // exported via serializeCFP, magic === 'CFP1'

// fixture authoring:
const fixture = serializeCFP(createEmptyCFP()); // guarantees magic: 'CFP1'

Defensive patterns

Strategy: validation

Validate before calling

// Pre-flight the magic field so a wrong file fails with your own message
const parsed = JSON.parse(raw) as { magic?: string };
if (parsed.magic !== 'CFP1') {
  throw new Error(`Not a CFP1 document (magic=${JSON.stringify(parsed.magic)}) — wrong file or unsupported version`);
}
const cfp = deserializeCFP(raw);

Type guard

function looksLikeCFP(value: unknown): value is { magic: 'CFP1' } {
  return typeof value === 'object' && value !== null && (value as { magic?: unknown }).magic === 'CFP1';
}

Try / catch

try {
  const cfp = deserializeCFP(raw);
} catch (e) {
  if (/expected magic 'CFP1'/.test(String((e as Error).message))) {
    throw new Error('Wrong or unsupported CFP version — check that the file is a CFP export (magic CFP1)');
  }
  throw e;
}

Prevention

Generate fixtures and exports via the library's own serialize functions so magic is always correct
When accepting CFP files from users, check parsed.magic === 'CFP1' before full deserialization
Treat other magic values (CFP2, undefined) as version/format mismatches, not corruption

When it happens

Trigger: deserializeCFP on JSON that is not a CFP document (any plain JSON file); on a future/incompatible CFP version (magic 'CFP2'); on a document where the magic field was dropped by a transform; on test fixtures hand-written without { magic: 'CFP1' }.

Common situations: Pointing the transfer import at the wrong file (e.g. a .json config mistaken for an exported pattern); schema evolution where producers bump the magic; middleware that strips unknown fields; fixtures built by hand instead of serializeToJson.

Related errors

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