angular/angular-cli · error · Error

Configuration error: found 'withAppShell()' without 'withRou

Error message

Configuration error: found 'withAppShell()' without 'withRoutes()' in the same call to 'provideServerRendering()'.The 'withAppShell()' function requires 'withRoutes()' to be used.

What it means

`provideServerRendering()` validates its feature combination: `withAppShell()` requires the server routes feature (`withRoutes()`) to be present in the same call. Without `withRoutes()`, there is no route configuration for the app shell to attach to, so the configuration is rejected at provider-creation time rather than failing later at runtime.

Source

Thrown at packages/angular/ssr/src/routes/route-config.ts:466

  } else {
    features = args;
  }

  const providers: (Provider | EnvironmentProviders)[] = [
    provideServerRenderingPlatformServer(options),
  ];

  let hasAppShell = false;
  let hasServerRoutes = false;

  for (const { ɵkind, ɵproviders } of features) {
    hasAppShell ||= ɵkind === ServerRenderingFeatureKind.AppShell;
    hasServerRoutes ||= ɵkind === ServerRenderingFeatureKind.ServerRoutes;
    providers.push(...ɵproviders);
  }

  if (!hasServerRoutes && hasAppShell) {
    throw new Error(
      `Configuration error: found 'withAppShell()' without 'withRoutes()' in the same call to 'provideServerRendering()'.` +
        `The 'withAppShell()' function requires 'withRoutes()' to be used.`,
    );
  }

  return makeEnvironmentProviders(providers);
}

/**
 * Checks if the first element of args is a `ServerRenderingOptions` object.
 */
function hasOptions(
  args:
    | ServerRenderingFeature<ServerRenderingFeatureKind>[]
    | [ServerRenderingOptions, ...ServerRenderingFeature<ServerRenderingFeatureKind>[]],
): args is [ServerRenderingOptions, ...ServerRenderingFeature<ServerRenderingFeatureKind>[]] {
  const value = args[0];

View on GitHub (pinned to bb72145f9a)

Solutions

Add `withRoutes(serverRoutes)` to the same `provideServerRendering()` call, typically before `withAppShell()`.
Define your server routes (`ServerRoute[]`) in `app.routes.server.ts` and pass them to `withRoutes()`.
If you don't need an app shell, remove `withAppShell()` and keep only `withRoutes()`.
Re-check the official `app.config.server.ts` example in the @angular/ssr docs for the correct feature order.

Example fix

// before
export default provideServerRendering(withAppShell(AppShellComponent));
// after
export default provideServerRendering(
  withRoutes(serverRoutes),
  withAppShell(AppShellComponent),
);

Defensive patterns

Strategy: validation

Validate before calling

// sanity check in app.config.server.ts
const features = [withRoutes(serverRoutes), withAppShell(AppShellComponent)];
if (!features.some(f => /* routes feature present */ serverRoutes.length >= 0)) {
  throw new Error('withAppShell() requires withRoutes()');
}
export default provideServerRendering(...features);

Type guard

function hasRoutesFeature(features: { ɵkind: ServerRenderingFeatureKind }[]): boolean {
  return features.some(f => f.ɵkind === ServerRenderingFeatureKind.ServerRoutes);
}

Try / catch

try {
  const providers = provideServerRendering(withAppShell(AppShellComponent));
} catch (e) {
  if (String(e?.message).includes("withAppShell()' without 'withRoutes()")) {
    console.error('Add withRoutes(serverRoutes) to provideServerRendering()');
  } else throw e;
}

Prevention

Always pair `withAppShell()` with `withRoutes()` in the same `provideServerRendering()` call.
Keep `app.config.server.ts` aligned with the current @angular/ssr docs when upgrading.
Run `ng build` (even dev) in CI so provider-configuration errors surface before deploy.
Prefer the official starter's `app.config.server.ts` as the template and modify minimally.

When it happens

Trigger: Calling `provideServerRendering(withAppShell(AppShellComponent))` without also passing `withRoutes([...])` in the same call, e.g. in `app.config.server.ts` after a migration that dropped the routes feature.

Common situations: Migrating from the old `AngularAppEngine`/`CommonEngine` setup to the new `provideServerRendering` API and forgetting `withRoutes`; copying a minimal SSR example that only used `withRoutes()` then adding an app shell; a codemod partial migration.

Related errors

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