angular/angular-cli · error · Error

Unknown format - version specifier not found.

Error message

Unknown format - version specifier not found.

What it means

The reader requires a top-level 'version' property to identify the workspace format. If the parsed object has no 'version' node (findNodeAtLocation returns falsy), it throws this Error. The version field is the format contract of angular.json.

Source

Thrown at packages/angular_devkit/core/src/workspace/json/reader.ts:59

export async function readJsonWorkspace(
  path: string,
  host: WorkspaceHost,
  options: JsonWorkspaceOptions = {},
): Promise<WorkspaceDefinition> {
  const raw = await host.readFile(path);
  if (raw === undefined) {
    throw new Error('Unable to read workspace file.');
  }

  const ast = parseTree(raw, undefined, { allowTrailingComma: true, disallowComments: false });
  if (ast?.type !== 'object' || !ast.children) {
    throw new Error('Invalid workspace file - expected JSON object.');
  }

  // Version check
  const versionNode = findNodeAtLocation(ast, ['version']);
  if (!versionNode) {
    throw new Error('Unknown format - version specifier not found.');
  }
  const version = versionNode.value;
  if (version !== 1) {
    throw new Error(`Invalid format version detected - Expected:[ 1 ] Found: [ ${version} ]`);
  }

  const context: ParserContext = {
    host,
    metadata: new JsonWorkspaceMetadata(path, ast, raw),
    trackChanges: true,
    unprefixedWorkspaceExtensions: new Set([
      ...ANGULAR_WORKSPACE_EXTENSIONS,
      ...(options.allowedWorkspaceExtensions ?? []),
    ]),
    unprefixedProjectExtensions: new Set([
      ...ANGULAR_PROJECT_EXTENSIONS,
      ...(options.allowedProjectExtensions ?? []),
    ]),

View on GitHub (pinned to bb72145f9a)

Solutions

1. Add "version": 1 to the top level of the workspace file.
2. Regenerate the file with Angular CLI (ng generate config) to get a valid skeleton.
3. Restore from git if the version field was accidentally deleted.

Example fix

// before
{
  "projects": { "app": { "root": "apps/app" } }
}
// after
{
  "version": 1,
  "projects": { "app": { "root": "apps/app" } }
}

const parsed = JSON.parse(await readFile('angular.json', 'utf8'));
if (!('version' in parsed)) {
  throw new Error('angular.json is missing the required "version": 1 field');
}

function hasVersionField(ws: unknown): ws is { version: unknown } {
  return typeof ws === 'object' && ws !== null && 'version' in ws;
}

try {
  const ws = await readWorkspace('angular.json', host);
} catch (e) {
  if (e.message.includes('version specifier not found')) {
    console.error('Add "version": 1 to the top level of angular.json.');
  } else throw e;
}

When it happens

Trigger: angular.json missing the "version": 1 line (hand-written file, trimmed config, tool output that omitted it); a custom workspace-like file passed to readWorkspace.

Common situations: Writing angular.json manually and forgetting the version key; tools that regenerate only the 'projects' section; copying a partial example from docs.

Understand the failure class

Background: "Missing required field" and "field is required" errors: why libraries reject payloads that omit mandatory fields — this error's family across 20 libraries.

Related errors

• Invalid format version detected - Expected:[ 1 ] Found: [ ${
• Project name already exists.
• "${name}" must be a JSON value.
• Project name must be a valid npm package name.
• Target name already exists.

AI-assisted analysis of angular/angular-cli@bb72145f9a (2026-08-30). Data as JSON: /api/errors/0aa4bbcd09f4eebe. Report an issue: GitHub.