angular/angular-cli · warning

Project " " uses a custom Karma configuration file " "…

Error message

Project "${projectName}" uses a custom Karma configuration file "${karmaConfig}". Tests have been migrated to use Vitest, but you may need to manually migrate custom settings from this Karma config to a Vitest config (e.g. "vitest-base.config.ts") and set the "runnerConfig" option to true.

What it means

The Karma-to-Vitest migration can translate the builder options, but when a project points at a custom karma.conf.js that the processor cannot fully remove or translate, it warns that manual migration of custom settings into a Vitest config (e.g. vitest-base.config.ts) is required, and that the 'runnerConfig' option should be set to true.

Solutions

1. Review the custom karma.conf.js and port each custom setting (plugins, proxies, middleware, files, preprocessors) into your Vitest config (e.g. vitest-base.config.ts)
2. Set "runnerConfig": true on the test target options so Vitest uses your custom config
3. Remove the now-unused karma.conf.js once settings are ported
4. Run your test suite to confirm behavior matches the previous Karma setup

Example fix

// before (angular.json test target)
"karmaConfig": "src/karma.conf.js"
// after
"runnerConfig": true,
// plus a vitest-base.config.ts containing the ported custom settings

// before migrating, flag custom karma configs for manual porting
const opts = angularJson.projects[proj].architect?.test?.options || {};
if (opts.karmaConfig) {
  console.warn(`${proj} uses custom karma config ${opts.karmaConfig}; plan to port settings to a Vitest config and set runnerConfig: true`);
}

When it happens

Trigger: Running processKarmaConfig during the migrate-karma-to-vitest migration when the project's test target specifies a custom karmaConfig file whose parsed analysis is not flagged as removable (custom plugins, frameworks, middlewares, proxies, etc.).

Common situations: Large Angular workspaces with hand-tuned karma.conf.js (webpack customizations, coverage thresholds, custom reporters, proxies) migrating tests to Vitest during an Angular CLI version migration.

Related errors

• - ${file}
• Project " " uses a custom coverage reporter " ". This…
• The following Karma configuration files require manual…
• Cannot add a Vitest configuration as builder for "test"…
• - x

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

Appendix: source

Thrown at packages/schematics/angular/migrations/migrate-karma-to-vitest/karma-processor.ts:163

      const diff = await compareKarmaConfigToDefault(
        analysis,
        projectName,
        karmaConfig,
        needDevkitPlugin,
      );
      isRemovable = !hasDifferences(diff) && diff.isReliable;
    }

    cachedResult = { analysis, isRemovable };
    cache.set(karmaConfig, cachedResult);
  }

  if (cachedResult) {
    extractReporters(cachedResult.analysis, options, projectName, context);
    extractCoverageSettings(cachedResult.analysis, options, projectName, context);

    if (!cachedResult.isRemovable) {
      context.logger.warn(
        `Project "${projectName}" uses a custom Karma configuration file "${karmaConfig}". ` +
          `Tests have been migrated to use Vitest, but you may need to manually migrate custom settings ` +
          `from this Karma config to a Vitest config (e.g. "vitest-base.config.ts") ` +
          `and set the "runnerConfig" option to true.`,
      );
      manualMigrationFiles.push(karmaConfig);
    }
  }

  delete options['karmaConfig'];
}

View on GitHub (pinned to bb72145f9a)