angular/angular-cli · error · Error

Unable to read workspace file.

Error message

Unable to read workspace file.

What it means

readJsonWorkspace reads the file via host.readFile(path); if the host returns undefined (file missing/unreadable) it throws 'Unable to read workspace file.' It is the reader's hard failure for an inaccessible workspace file, before any JSON parsing occurs.

Source

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

  readonly unprefixedWorkspaceExtensions: ReadonlySet<string>;
  readonly unprefixedProjectExtensions: ReadonlySet<string>;
  error(message: string, node: JsonValue): void;
  warn(message: string, node: JsonValue): void;
}

export interface JsonWorkspaceOptions {
  allowedProjectExtensions?: string[];
  allowedWorkspaceExtensions?: string[];
}

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 = {

View on GitHub (pinned to bb72145f9a)

Solutions

1. Verify the workspace file exists at the given path and the process CWD/root is correct.
2. Ensure the WorkspaceHost (e.g. createWorkspaceHost / virtual fs) is rooted where the file lives.
3. Create the workspace file (ng new / workspace config) before reading.
4. Catch this error and prompt the user for a valid workspace path.

Example fix

// before
const ws = await readWorkspace('angluar.json', host); // typo
// after
const ws = await readWorkspace('angular.json', host);

import { existsSync } from 'fs';
if (!existsSync(workspacePath)) {
  throw new Error(`No workspace file at ${workspacePath}; run inside an Angular workspace`);
}
const ws = await readWorkspace(workspacePath, host);

function workspaceFileExists(path: string, host: WorkspaceHost): Promise<boolean> {
  return host.readFile(path).then(raw => raw !== undefined);
}

try {
  const ws = await readWorkspace('angular.json', host);
} catch (e) {
  if (e.message === 'Unable to read workspace file.') {
    console.error('No angular.json found; run `ng new` or cd into the workspace root.');
    process.exitCode = 1;
  } else throw e;
}

When it happens

Trigger: Calling readWorkspace('angular.json', host) when angular.json does not exist at that path, the path is wrong, or the custom WorkspaceHost's readFile returns undefined (e.g. virtual fs without the file registered).

Common situations: Running schematics/tools outside an Angular workspace directory; typo'd filename (angular.json vs workspace.json); file deleted or not committed; custom host pointing at the wrong root.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• Confguration file cannot be 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/1672103caaa26cf4. Report an issue: GitHub.