avajs/ava · error · TypeError

The ’environmentVariables’ configuration must be an object c

Error message

The ’environmentVariables’ configuration must be an object containing string values.

What it means

The `environmentVariables` configuration option must be a plain object whose values are all strings, since its entries are passed to child test processes as actual environment variables. If any value is not a string, loadCli throws this TypeError during configuration validation.

Source

Thrown at lib/environment-variables.js:8

export default function validateEnvironmentVariables(environmentVariables) {
	if (!environmentVariables) {
		return {};
	}

	for (const value of Object.values(environmentVariables)) {
		if (typeof value !== 'string') {
			throw new TypeError('The ’environmentVariables’ configuration must be an object containing string values.');
		}
	}

	return environmentVariables;
}

View on GitHub (pinned to bbfd946322)

Solutions

1. Quote or convert every value to a string: `environmentVariables: {PORT: '3000'}`.
2. Use String() or template literals for computed values: `PORT: String(port)`.
3. Validate config values with typeof before passing them to AVA.
4. Check for build tooling (YAML loaders, dotenv munging) that turns quoted values into numbers/booleans.

Example fix

// before
environmentVariables: {PORT: 3000, DEBUG: true}
// after
environmentVariables: {PORT: '3000', DEBUG: 'true'}

const env = config.environmentVariables;
if (env !== undefined) {
  for (const [k, v] of Object.entries(env)) {
    if (typeof v !== 'string') throw new TypeError(`environmentVariables.${k} must be a string (got ${typeof v})`);
  }
}

const isValidEnvVars = v => v === undefined || (typeof v === 'object' && v !== null && Object.values(v).every(x => typeof x === 'string'));

try {
  await run();
} catch (err) {
  if (err instanceof TypeError && err.message.includes('environmentVariables')) {
    console.error('Fix environmentVariables values to be strings in your AVA config');
    process.exitCode = 1;
  } else throw err;
}

When it happens

Trigger: Setting `environmentVariables` in ava.config.js/package.json to an object containing a non-string value — e.g. `environmentVariables: {PORT: 3000}` or `{DEBUG: true}` — then running the AVA CLI.

Common situations: Using numeric ports or booleans in config; YAML/JSON5 config files where unquoted values become numbers; programmatic `ava` API calls passing non-string env values.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• The extensions option must be an array
• ${fileForErrorMessage} must export a plain object or factory
• Unexpected duplicate extensions in options: ’${[...duplicate
• The ’files’ configuration must be an array containing glob p
• The ’watchMode.ignoreChanges’ configuration must be an array

AI-assisted analysis of avajs/ava@bbfd946322 (2026-09-02). Data as JSON: /api/errors/0b16961ac31022e0. Report an issue: GitHub.