eslint/eslint · error · Error

Schema for rule ${ruleName} is invalid: ${err.message}

Error message

Schema for rule ${ruleName} is invalid: ${err.message}

What it means

Thrown during RuleTester.run() at lib/rule-tester/rule-tester.js:1272 when `ajv.validateSchema(schema)` passed (the schema is structurally well-formed) but `ajv.compile(schema)` throws. Compile-time errors are problems that only surface when ajv turns the schema into a validator — most commonly invalid `default` values that fail their own schema, cyclic or unresolvable `$ref`s, or keyword misuses that pass meta-validation but break compilation. The original error is attached as `cause`.

Source

Thrown at lib/rule-tester/rule-tester.js:1272

						})
						.join("\n");

					throw new Error([
						`Schema for rule ${ruleName} is invalid:`,
						errors,
					]);
				}

				/*
				 * `ajv.validateSchema` checks for errors in the structure of the schema (by comparing the schema against a "meta-schema"),
				 * and it reports those errors individually. However, there are other types of schema errors that only occur when compiling
				 * the schema (e.g. using invalid defaults in a schema), and only one of these errors can be reported at a time. As a result,
				 * the schema is compiled here separately from checking for `validateSchema` errors.
				 */
				try {
					ajv.compile(schema);
				} catch (err) {
					throw new Error(
						`Schema for rule ${ruleName} is invalid: ${err.message}`,
						{
							cause: err,
						},
					);
				}
			}

			// check for validation errors
			try {
				configs.normalizeSync();
				configs.getConfig("test.js");
			} catch (error) {
				error.message = `ESLint configuration in rule-tester is invalid: ${error.message}`;
				throw error;
			}

			// Verify the code.

View on GitHub (pinned to f131c034ad)

Solutions

1. Inspect `err.message` (and the `cause`) in the thrown error — it typically names the failing keyword or default.
2. Make every `default` validate against its own subschema (e.g. for `enum: ["a","b"]`, the default must be one of those).
3. Resolve/inline any `$ref` and confirm referenced definitions exist and are not cyclic in an unsupported way.
4. Compile the schema in isolation to iterate faster: `try { ajv.compile(yourSchema) } catch (e) { console.error(e.message); }`.

Example fix

// before
meta: {
  schema: [{
    enum: ["always", "never"],
    default: "sometimes"
  }]
}

// after
meta: {
  schema: [{
    enum: ["always", "never"],
    default: "always"
  }]
}

const Ajv = require('ajv');
function compileStandalone(schema) {
  const ajv = new Ajv();
  ajv.validateSchema(schema); // structural first
  if (ajv.errors) throw new Error('structural: ' + ajv.errorsText(ajv.errors));
  try { ajv.compile(schema); } // compile-time (defaults, refs)
  catch (e) { throw new Error('compile: ' + e.message); }
}

/** @param {object} schema */
function defaultsValidateAgainstSelf(schema) {
  const check = (node) => {
    if (!node || typeof node !== 'object') return true;
    if ('default' in node) {
      if ('enum' in node && !node.enum.includes(node.default)) return false;
      if (node.type === 'string' && typeof node.default !== 'string') return false;
      if (node.type === 'number' && typeof node.default !== 'number') return false;
      if (node.type === 'boolean' && typeof node.default !== 'boolean') return false;
    }
    return Object.values(node).every(check);
  };
  return check(schema);
}

When it happens

Trigger: A rule's `meta.schema` includes a `default` value that does not validate against its own constraints (e.g. `default: 5` with `type: "string"`), an unresolvable `$ref`, or another structural issue that only fails at compile time. RuleTester compiles the schema explicitly after the structural check to surface exactly one such error.

Common situations: Adding a `default` that contradicts the keyword's type/enum; renaming a definition but forgetting to update the `$ref`; using a keyword from a draft ajv isn't configured for; schema regression after a refactor.

Related errors

• Schema for rule ${ruleName} is invalid:
• `schema: {}` is a no-op${metaSchemaDescription}
• ESLINT_INVALID_RULE_OPTIONS_SCHEMA
• Key "rules": Key "${ruleId}":
• Use ${objName}.range[0] instead of ${objName}.start

AI-assisted analysis of eslint/eslint@f131c034ad (2026-08-03). Data as JSON: /data/errors/7ad51098a01905d9.json. Report an issue: GitHub.