Postconditions: what we check

• validate · validate-returns-error

  error
  Whendata fails validation against the schema
  Returns{error: ValidationError, value: any} where error contains validation failure details
  Required handlingCaller MUST check result.error property before using result.value. Without checking error, invalid data will pass through silently, leading to data corruption, business logic errors, or security vulnerabilities. Use pattern: const { error, value } = schema.validate(data); if (error) { /* handle */ }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• validateAsync · validateasync-rejects

  error
  Whendata fails validation against the schema
  ThrowsPromise rejection with ValidationError
  Required handlingCaller MUST wrap validateAsync() in try-catch or use .catch() handler. Without error handling, validation failures cause unhandled promise rejections that crash the application. Use pattern: try { const value = await schema.validateAsync(data); } catch (error) { /* handle */ }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• assert · assert-throws

  error
  Whendata fails validation against the schema
  ThrowsValidationError
  Required handlingCaller MUST wrap Joi.assert() in try-catch block. Without error handling, validation failures throw uncaught exceptions that crash the application. Use pattern: try { Joi.assert(value, schema); } catch (error) { /* handle */ }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3]
• attempt · attempt-throws

  error
  Whendata fails validation against the schema
  ThrowsValidationError
  Required handlingCaller MUST wrap Joi.attempt() in try-catch block. Without error handling, validation failures throw uncaught exceptions that crash the application. Use pattern: try { const validated = Joi.attempt(value, schema); } catch (error) { /* handle */ }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[4]
• compile · compile-invalid-schema-throws

  warning
  Whenschema argument is undefined, an empty array, or contains non-plain objects
  ThrowsAssertError (extends Error) from @hapi/hoek — message: 'Invalid undefined schema' or 'Invalid empty array schema' or 'Schema can only contain plain objects'
  Required handlingCaller MUST wrap Joi.compile() in try-catch when schema is built dynamically (e.g. from user input, config files, or database). Static schema definitions compiled at module load are safe if the schema literal is correct. Without error handling, invalid schema definitions throw at runtime and crash the request handler or service startup. Use pattern: try { const schema = Joi.compile(rawSchema); } catch (err) { /* handle */ }
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5][6]
• compile · compile-version-mismatch-throws

  warning
  Whenschema was compiled with a different version of joi (legacy: false, default)
  ThrowsAssertError — message: 'Cannot mix different versions of joi schemas: <version> <version>'
  Required handlingWhen using Joi.compile() with dynamically loaded schemas from external sources (plugins, serialized schemas), version mismatches throw AssertError. Use Joi.compile(schema, { legacy: true }) to allow older schema versions, or ensure all schemas are compiled with the same joi version.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5][6]
• extend · extend-empty-extensions-throws

  warning
  Whenextend() is called with zero arguments
  ThrowsAssertError from @hapi/hoek — message: 'You need to provide at least one extension'
  Required handlingCaller MUST pass at least one extension definition. When extensions are loaded dynamically (from a plugin loader, config file, or filesystem scan), wrap Joi.extend() in try-catch in case the plugin list is empty after filtering. Without error handling, an empty extension list crashes module initialization. Use pattern: try { customJoi = Joi.extend(...extensions); } catch (err) { /* handle */ }
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5][7]
• extend · extend-invalid-extension-shape-throws

  error
  Whenextension object fails Schemas.extension validation (missing type, invalid base, malformed rules)
  ThrowsValidationError from this.assert(extension, Schemas.extension) — wrapped AssertError
  Required handlingCaller MUST validate extension definitions before passing to extend() when extensions come from external sources (user-defined plugins, dynamic config). Each extension must have a string type field and optional base schema, prepare, coerce, validate, rules, and messages fields matching the documented shape. Use pattern: try { customJoi = Joi.extend(extensionDef); } catch (err) { /* handle */ }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5][8]
• extend · extend-override-existing-type-throws

  warning
  Whenextension attempts to define a type name that is not already in the instance's _types set (e.g. trying to override a primitive type name like 'string' without inheriting it as base)
  ThrowsAssertError — message: 'Cannot override name <type>'
  Required handlingWhen extending Joi to add new type names, ensure the name does not collide with built-in primitive types (string, number, boolean, etc.) unless explicitly inheriting via base. Common pitfall when adding a custom 'email' or 'url' type. Use pattern: try { customJoi = Joi.extend({ type: 'myCustomType', base: Joi.string(), ... }); } catch (err) { /* handle */ }
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[7]
• defaults · defaults-non-function-modifier-throws

  warning
  Whenmodifier argument is not a function (e.g. undefined, object, null)
  ThrowsAssertError from @hapi/hoek — message: 'modifier must be a function'
  Required handlingCaller MUST pass a function as the modifier argument. When the modifier comes from external config or is computed dynamically, validate it is a function before calling Joi.defaults(). Use pattern: try { customJoi = Joi.defaults(modifier); } catch (err) { /* handle */ }
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5][7]
• defaults · defaults-modifier-returns-non-schema-throws

  error
  Whenmodifier function returns a value that is not a joi schema object
  ThrowsAssertError from @hapi/hoek — message: 'modifier must return a valid schema object'
  Required handlingModifier function MUST return a joi schema for every input schema. Common mistakes: forgetting to return (returns undefined), returning a plain object instead of calling .object() on it, returning the input unchanged when the modifier mutates instead of returning. Use pattern: Joi.defaults((schema) => schema.required()) — always return the schema.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5][7]

Sources

Every postcondition cites at least one of these. Grouped by source type; numbered to match the footnotes above.

Research notes

Curator notes from SOURCES.md captured when the profile was written so you can verify the reasoning, not just the rules.

const {error, warning, value} = finalSchema.validate(options, {
  convert: false,
});

printWarning(warning);

if (error) {
  throw error;  // ✅ Properly checks and throws
}

return value;

const personSchema = Joi.object({
  age: Joi.number().required(),
  name: Joi.string().required(),
});

router.post(validate({ body: personSchema }), (req, res) => {
  const person = req.body;  // ✅ Middleware handles validation
  return res.status(201).json({ data: person });
});

// ❌ WRONG
const { value } = schema.validate(data);
doSomething(value);  // May be invalid!

// ❌ WRONG
const value = await schema.validateAsync(data);  // No try-catch

// ❌ WRONG
Joi.assert(data, schema);  // Will crash if validation fails