hapijs/joi · error · Error

Unsupported JSON Schema target: ${options.target}

Error message

Unsupported JSON Schema target: ${options.target}

What it means

joi's $_jsonSchema() serializes a schema to JSON Schema (draft 2020-12). The library only supports the JSON Schema target it was built against (internals.jsonSchemaTarget), so passing any other target string throws this error at lib/base.js:75. It is a fail-fast guard because joi cannot guarantee correct output for other draft versions.

Source

Thrown at lib/base.js:75

            ruleset: null,                          // null: use last, false: error, number: start position
            whens: {}                               // Runtime cache of generated whens
        };
    }

    // Manifest

    describe() {

        assert(typeof Manifest.describe === 'function', 'Manifest functionality disabled');
        return Manifest.describe(this);
    }

    $_jsonSchema(mode, options = {}) {

        if (options.target !== undefined &&
            options.target !== internals.jsonSchemaTarget) {

            throw new Error(`Unsupported JSON Schema target: ${options.target}`);
        }

        const rootCall = !options.$defs;
        const defs = options.$defs ?? {};

        let schema = {};

        const isTypeAny = this.type === 'any';
        const isOnly = this._flags.only;

        const valids = this._valids && Array.from(this._valids._values).filter((v) => v !== null);
        let typesOverlap = true;

        // If 'only' is set, check if the allowed values' types overlap with the schema type

        if (valids && valids.length && isOnly && !isTypeAny) {
            const types = new Set(valids.map((v) => typeof v));
            typesOverlap = types.has(this.type) || (this.type === 'date' && types.has('object'));

View on GitHub (pinned to 58ce83e919)

Solutions

Remove the options.target property entirely and let joi use its built-in default target (internals.jsonSchemaTarget, currently '2020-12').
Set target to the version joi supports — check the value documented for your installed joi version (npm ls joi, then the docs) and use that exact string, e.g. { target: '2020-12' }.
If you need a different draft, generate with joi's supported target and convert the output with a converter tool instead of asking joi for it.
Upgrade or downgrade joi to a version whose JSON Schema target matches the one your toolchain requires.

Example fix

// before
const jsonSchema = schema.$_jsonSchema({ target: 'draft-07' });
// after
const jsonSchema = schema.$_jsonSchema(); // uses joi's supported target (2020-12)

Defensive patterns

Strategy: validation

Validate before calling

const SUPPORTED_TARGET = '2020-12'; // check docs for your joi version
if (options?.target !== undefined && options.target !== SUPPORTED_TARGET) {
  throw new TypeError(`target must be omitted or '${SUPPORTED_TARGET}', got: ${options.target}`);
}
const jsonSchema = schema.$_jsonSchema(options);

Type guard

function hasValidTarget(options) {
  const SUPPORTED = '2020-12';
  return !options || options.target === undefined || options.target === SUPPORTED;
}

Try / catch

let jsonSchema;
try {
  jsonSchema = schema.$_jsonSchema(options);
} catch (err) {
  if (err.message.startsWith('Unsupported JSON Schema target')) {
    jsonSchema = schema.$_jsonSchema(); // fall back to default target
  } else {
    throw err;
  }
}

Prevention

Omit options.target unless you specifically need it — the default is always supported.
Pin your joi version in package.json so the supported target doesn't change under you.
Centralize JSON Schema export in one helper that owns the target constant.
When integrating with standard-schema tooling, verify which draft the tool expects before passing its target through.

When it happens

Trigger: Calling schema.$_jsonSchema({ target: 'draft-07' }) or any target other than '2020-12' (e.g. 'draft-4', 'openapi-3.0'); also occurs when using $standard/standard-schema integration (~standard) with options.target set by tooling to an unsupported draft.

Common situations: Copy-pasting JSON Schema export options from another library's docs; upgrading/downgrading joi so the supported draft no longer matches a hardcoded target in build scripts or OpenAPI generators; configuring a validator plugin (e.g. standard-schema consumers) with an explicit target.

Related errors

result.error.details[0].message

AI-assisted analysis of hapijs/joi@58ce83e919 (2026-09-01). Data as JSON: /api/errors/7caf4a0cd7875ebe. Report an issue: GitHub.