Unsupported schematic context. Expected a FileSystemSchemati

Error message

Unsupported schematic context. Expected a FileSystemSchematicContext.

What it means

Thrown by the URL handler created in createSourceFromUrl when a `file:` (or empty) URL source runs with a context whose schematic description lacks a `path` property. File-based schematics resolve relative file URLs against the schematic's own directory, which is only known for a FileSystemSchematicContext.

Source

Thrown at packages/angular_devkit/schematics/tools/file-system-engine-host-base.ts:286

      ...partialDesc,
      schema,
      schemaJson,
      name,
      path,
      factoryFn: resolvedRef.ref,
      collection,
    });
  }

  createSourceFromUrl(url: Url): Source | null {
    switch (url.protocol) {
      case null:
      case 'file:':
        return (context) => {
          // Check if context has necessary FileSystemSchematicContext path property
          const fileDescription = context.schematic.description as { path?: string };
          if (fileDescription.path === undefined) {
            throw new Error(
              'Unsupported schematic context. Expected a FileSystemSchematicContext.',
            );
          }

          // Resolve all file:///a/b/c/d from the schematic's own path, and not the current
          // path.
          const root = normalize(resolve(fileDescription.path, url.path || ''));

          return new HostCreateTree(new virtualFs.ScopedHost(new NodeJsSyncHost(), root));
        };
    }

    return null;
  }

  transformOptions<OptionT extends object, ResultT extends object>(
    schematic: FileSystemSchematicDesc,
    options: OptionT,

View on GitHub (pinned to bb72145f9a)

Solutions

Obtain the context from the same engine/host that runs the schematic (e.g. FileSystemEngineHost / SchematicTestRunner) so it is a FileSystemSchematicContext.
Ensure the executing schematic's description has `path` set (i.e. it was created by createSchematicDescription of the file-system host).
If you must use a custom context, use a non-file Url source instead.

Example fix

// before
const context = { schematic: { description: { name: 'x' } } } as any;
engine.createSourceFromUrl(new Url('file:./files'), context);
// after (use a real context from the file-system engine)
const context = host.createContext({}); // FileSystemSchematicContext with description.path
engine.createSourceFromUrl(new Url('file:./files'), context);

Defensive patterns

Strategy: type-guard

Type guard

function isFileSystemContext(ctx: unknown): ctx is FileSystemSchematicContext {
  const d = (ctx as any)?.schematic?.description;
  return !!d && typeof d.path === 'string' && d.path.length > 0;
}

if (!isFileSystemContext(context)) throw new Error('Expected FileSystemSchematicContext');

Try / catch

try {
  const source = engine.createSourceFromUrl(new Url('file:./files'), context);
} catch (e) {
  if (String(e.message).includes('Unsupported schematic context')) {
    throw new Error('Create the context via the FileSystemEngineHost, not manually');
  }
  throw e;
}

Prevention

Always obtain SchematicContext objects from the same engine host that runs the schematic.
In tests use SchematicTestRunner / UnitTestTree rather than fabricating contexts.
Avoid casting arbitrary objects with `as any` into SchematicContext.

When it happens

Trigger: Calling engine.createSourceFromUrl(new Url('file:...')) (or null) and passing a context that is not a FileSystemSchematicContext — e.g. a plain object context or a context created by another engine — so `context.schematic.description.path` is undefined.

Common situations: Custom tooling that builds a SchematicContext manually instead of through the FileSystemEngineHost; invoking a file: source from a test with a stubbed context; mixing engine hosts (NodeModuleEngineHost context used with a file: source).

Related errors

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