Unknown install content transform

Error message

Unknown install content transform: ${operation.contentTransform}

What it means

transformCopyFileContent applies a named content transform to a file's content during a copy-file install operation. The library only recognizes the built-in transform 'antigravity-agent-frontmatter'; if an operation record carries a contentTransform value it does not know, it refuses to guess and throws. This guards against silently copying a file whose content was meant to be adapted (e.g. frontmatter rewritten for a different agent harness).

Solutions

Log or inspect the operation's contentTransform value and correct the spelling so it matches 'antigravity-agent-frontmatter' exactly.
Remove the contentTransform field from the operation if no transformation is actually needed (the source content will be copied verbatim).
Update the ECC checkout to the version that defines the transform used by the operation record.
If a new transform is genuinely required, add a branch in transformCopyFileContent (scripts/lib/install-lifecycle.js:233) that dispatches to an adapter function, mirroring the adaptAntigravityAgent branch.

Example fix

// before (install-state / operation data)
{ "kind": "copy-file", "contentTransform": "antigravity-agent-frontmatter2", ... }

// after
{ "kind": "copy-file", "contentTransform": "antigravity-agent-frontmatter", ... }

Defensive patterns

Strategy: validation

Validate before calling

const KNOWN_TRANSFORMS = ['antigravity-agent-frontmatter'];
function assertKnownTransform(op) {
  if (op.contentTransform && !KNOWN_TRANSFORMS.includes(op.contentTransform)) {
    throw new Error(`Unsupported contentTransform: ${op.contentTransform}`);
  }
}

Type guard

function hasKnownTransform(op) {
  return !op.contentTransform || op.contentTransform === 'antigravity-agent-frontmatter';
}

Try / catch

try {
  install(operations);
} catch (err) {
  if (/Unknown install content transform/.test(err.message)) {
    console.error(`Fix or drop contentTransform in: ${err.message}`);
  } else throw err;
}

Prevention

Treat contentTransform as an enum: only assign values the installed library version defines.
Validate operation records with a schema (enum of allowed transforms) before running installs.
Keep ECC checkout and install-state versions in sync; reinstall after upgrades.

When it happens

Trigger: A copy-file operation (from install-state, manifests/install-components.json, or repair hydration) has a non-empty operation.contentTransform string that is not exactly 'antigravity-agent-frontmatter' — e.g. a typo like 'antigravity-agent-fronmatter', a transform added in a newer ECC version while running an older script, or hand-edited install state.

Common situations: Hand-editing or tooling-mutating the install state file and introducing a new transform name; running an older checkout of ECC against state written by a newer version that introduced additional transforms; a contributor adding a new transform to operation data without implementing it in transformCopyFileContent.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

AI-assisted analysis of affaan-m/ECC@8321021c54 (2026-09-16). Data as JSON: /api/errors/cc774736820629dd. Report an issue: GitHub.

Appendix: source

Thrown at scripts/lib/install-lifecycle.js:233

function buildLinkIndexForOperations(operations, trustedRoot) {
  const mappings = (operations || [])
    .filter(operation => operation.kind === 'copy-file' && operation.sourceRelativePath)
    .map(operation => ({
      sourceRel: operation.sourceRelativePath,
      destRel: path.relative(trustedRoot, operation.destinationPath),
    }));
  return buildInstallIndex(mappings);
}

function transformCopyFileContent(operation, content) {
  if (!operation.contentTransform) {
    return content;
  }
  if (operation.contentTransform === 'antigravity-agent-frontmatter') {
    return adaptAntigravityAgent(content, operation.sourceRelativePath);
  }
  throw new Error(`Unknown install content transform: ${operation.contentTransform}`);
}

function getExpectedCopyFileContent(operation, content, linkIndex) {
  const transformed = transformCopyFileContent(operation, content);
  if (!linkIndex || !operation.sourceRelativePath || !isMarkdownPath(operation.destinationPath)) {
    return transformed;
  }
  return rewriteRelativeLinks(transformed, {
    sourceRel: operation.sourceRelativePath,
    index: linkIndex,
  });
}

function isPlainObject(value) {
  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
}

function cloneJsonValue(value) {

View on GitHub (pinned to 8321021c54)