joi

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]

Sources

Every postcondition cites at least one of these. Numbered to match the footnotes above.

1. [1]joi.dev/apihttps://joi.dev/api/#anyvalidatevalue-options
2. [2]joi.dev/apihttps://joi.dev/api/#anyvalidateasyncvalue-options
3. [3]joi.dev/apihttps://joi.dev/api/#assertvalue-schema-message-options
4. [4]joi.dev/apihttps://joi.dev/api/#attemptvalue-schema-message-options
5. [5]raw.githubusercontent.com/hapijs/joihttps://raw.githubusercontent.com/hapijs/joi/master/API.md
6. [6]github.com/hapijs/joihttps://github.com/hapijs/joi/blob/master/lib/compile.js