Cannot adapt Antigravity agent

Error message

Cannot adapt Antigravity agent ${label}: frontmatter must be an object

What it means

After the frontmatter block is matched and loaded with js-yaml, splitFrontmatter requires the parsed value to be a non-null, non-array object. Frontmatter must hold key/value metadata (name, description, etc.); scalars, arrays, or null mean the agent cannot be adapted for Antigravity, so it throws. This is a shape check on the parsed YAML document.

Solutions

Rewrite the frontmatter as a YAML mapping, e.g. 'name: my-agent' plus 'description: ...'.
Ensure the block is non-empty so js-yaml does not load it as null.
Do not use a top-level YAML sequence; wrap entries under named keys.
Run js-yaml.load on the block locally to confirm it yields a plain object before installing.

Example fix

// before (parses to null)
---
---
// after
---
name: my-agent
description: Agent description
---

Defensive patterns

Strategy: type-guard

Validate before calling

const yaml = require('js-yaml');
const m = String(source || '').match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n/);
const fm = m && yaml.load(m[1]);
if (!fm || typeof fm !== 'object' || Array.isArray(fm)) throw new Error(`${label}: frontmatter must be a YAML mapping`);

Type guard

const isFrontmatterObject = (v) => Boolean(v) && typeof v === 'object' && !Array.isArray(v);

Prevention

Validate that every agent's frontmatter loads as a non-empty object in a pre-install lint step.
Never leave the frontmatter block empty; include at least name and description keys.
Avoid top-level YAML sequences in agent frontmatter.

When it happens

Trigger: A frontmatter block that parses to a scalar (e.g. just 'true' or a string), a YAML list ('- item'), an empty block that loads as null, or YAML using a top-level sequence/mapping anchor that yields an array.

Common situations: Hand-edited frontmatter where all keys were accidentally deleted (empty '---\n---' parses to null); frontmatter written as a YAML list; a copy/paste that replaced the key-value metadata with a single line of text.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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

Appendix: source

Thrown at scripts/lib/install/antigravity-agent.js:31

const MODEL_NAMES = Object.freeze({
  haiku: 'flash',
  sonnet: 'pro',
  opus: 'pro',
});

function splitFrontmatter(source, label) {
  const match = String(source || '').match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n/);
  if (!match) {
    throw new Error(`Cannot adapt Antigravity agent ${label}: missing YAML frontmatter`);
  }

  // Keep YAML loading behind the transform boundary. Public help commands load
  // the installer graph without executing a transform, including in hermetic
  // packed-artifact checks where runtime dependencies are intentionally absent.
  const frontmatter = require('js-yaml').load(match[1]);
  if (!frontmatter || typeof frontmatter !== 'object' || Array.isArray(frontmatter)) {
    throw new Error(`Cannot adapt Antigravity agent ${label}: frontmatter must be an object`);
  }

  return {
    frontmatter,
    body: source.slice(match[0].length),
  };
}

function normalizeToolNames(value) {
  const names = Array.isArray(value) ? value : String(value || '').split(',');
  return [...new Set(names
    .map(name => String(name).trim())
    .filter(name => Object.hasOwn(TOOL_NAMES, name))
    .map(name => TOOL_NAMES[name]))];
}

function adaptAntigravityAgent(source, label = '<unknown>') {
  const { frontmatter, body } = splitFrontmatter(source, label);

View on GitHub (pinned to 8321021c54)