Invalid collection.json; schematics needs to be an object.

Error message

Invalid collection.json; schematics needs to be an object.

What it means

The blank schematic factory's addSchematicToCollectionJson rule reads the target collection.json from the virtual Tree and requires both the root document and its 'schematics' property to be JSON objects before inserting the new schematic entry. This error is thrown when either check fails, because the factory cannot safely write schematics['<name>'] into a malformed collection file. It is a deliberate sanity guard so the schematic never corrupts or misinterprets an invalid collection manifest.

Source

Thrown at packages/angular_devkit/schematics_cli/blank/factory.ts:34

  applyTemplates,
  chain,
  mergeWith,
  move,
  url,
} from '@angular-devkit/schematics';
import { NodePackageInstallTask } from '@angular-devkit/schematics/tasks';
import { Schema } from './schema';

function addSchematicToCollectionJson(
  collectionPath: Path,
  schematicName: string,
  description: JsonObject,
): Rule {
  return (tree: Tree) => {
    const collectionJson = tree.readJson(collectionPath);

    if (!isJsonObject(collectionJson) || !isJsonObject(collectionJson.schematics)) {
      throw new Error('Invalid collection.json; schematics needs to be an object.');
    }

    collectionJson['schematics'][schematicName] = description;
    tree.overwrite(collectionPath, JSON.stringify(collectionJson, undefined, 2));
  };
}

export default function (options: Schema): Rule {
  const schematicsVersion = require('@angular-devkit/schematics/package.json').version;
  const coreVersion = require('@angular-devkit/core/package.json').version;

  // Verify if we need to create a full project, or just add a new schematic.
  return (tree: Tree, context: SchematicContext) => {
    if (!options.name) {
      throw new SchematicsException('name option is required.');
    }

    let collectionPath: Path | undefined;

View on GitHub (pinned to bb72145f9a)

Solutions

Open collection.json and ensure the root is a JSON object containing a 'schematics': { ... } object, then rerun the schematic.
If the file is for a different purpose or corrupted beyond repair, restore a valid collection.json (e.g. from version control) with a schematics object.
If you only meant to create a brand-new project, remove the pre-existing collection.json so the blank schematic generates a fresh, valid one instead of augmenting it.

Example fix

// before (collection.json)
{
  "schematics": []
}

// after
{
  "schematics": {}
}

Defensive patterns

Strategy: validation

Validate before calling

const fs = require('fs');
function collectionJsonIsValid(path) {
  const json = JSON.parse(fs.readFileSync(path, 'utf8'));
  return typeof json === 'object' && json !== null && !Array.isArray(json) &&
    typeof json.schematics === 'object' && json.schematics !== null && !Array.isArray(json.schematics);
}
if (fs.existsSync('collection.json') && !collectionJsonIsValid('collection.json')) {
  throw new Error('collection.json must be an object with an object-valued "schematics" field');
}

Type guard

function isJsonObject(v) {
  return typeof v === 'object' && v !== null && !Array.isArray(v);
}

Try / catch

try {
  await schematicRunner.executeBlank({ name });
} catch (err) {
  if (err.message.includes('schematics needs to be an object')) {
    // repair or regenerate collection.json, then retry
  } else { throw err; }
}

Prevention

Validate collection.json against the schematics collection schema before running generators.
Never wrap 'schematics' in an array; always keep it as a plain object keyed by schematic name.
Keep collection.json in version control so hand-edit mistakes can be reverted.
Run with --dry-run first when pointing a schematic at an existing collection.

When it happens

Trigger: Running the blank schematic against a collection.json that is not a JSON object (e.g. a JSON array or scalar) or whose 'schematics' field is missing or not an object (e.g. an array, string, or absent). This happens inside addSchematicToCollectionJson when updating an existing collection.

Common situations: Hand-edited collection.json that lost the 'schematics' key or wrapped schematics in the wrong shape; a collection.json copied from a different schema (e.g. builder or migration collections); trailing corruption or a placeholder file created before fields were filled in.

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 angular/angular-cli@bb72145f9a (2026-08-30). Data as JSON: /api/errors/e01825a397086ccf. Report an issue: GitHub.