Postconditions: what we check

• route · route-handler-error

  error
  Whenroute handler throws error or promise rejects (database error, validation error)
  ThrowsError causing 500 Internal Server Error response if not handled - this will crash the application.
  Required handlingRoute handlers MUST handle errors with try-catch or return error via h.response().code() to prevent server crash and provide proper error responses. Use h.response(error).code(statusCode) for controlled error responses.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• start · start-error

  error
  Whenserver fails to start (port in use, invalid configuration, plugin error)
  ThrowsError with startup failure details
  Required handlingCaller MUST wrap server.start() in try-catch to handle startup errors. Port conflicts, plugin failures, and configuration errors crash application if unhandled.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• initialize · initialize-plugin-not-registered

  error
  Whencalled before async plugin registration callbacks have completed
  ThrowsError: 'Cannot start server before plugins finished registration'
  Required handlingCaller MUST await all server.register() calls to completion before calling server.initialize(). Calling initialize() during concurrent plugin registration throws synchronously and leaves server in an unusable state.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3]
• initialize · initialize-invalid-phase

  error
  Whencalled when server is not in 'stopped' phase (already initializing, starting, or started)
  ThrowsError: 'Cannot initialize server while it is in <phase> phase'
  Required handlingCall server.initialize() only once from the 'stopped' phase. Repeated initialization is a no-op if already 'initialized', but throws if in any other active phase. Wrap in try-catch to handle race conditions in concurrent startup code.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3]
• initialize · initialize-cache-start-error

  error
  Whencache engine fails to connect or start (Redis unavailable, Memcached unreachable)
  ThrowsError from catbox cache client — connection refused, authentication failure, or timeout
  Required handlingWrap server.initialize() in try-catch. Cache connection failures during initialization set the server phase to 'invalid', meaning the server CANNOT be recovered without process restart. Log the error and exit the process.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilitysilent
  Sources[3][4]
• stop · stop-invalid-phase

  error
  Whencalled while server is in 'stopping', 'starting', or 'initializing' phase
  ThrowsError: 'Cannot stop server while in <phase> phase'
  Required handlingAvoid calling stop() concurrently or during active phase transitions. In graceful shutdown handlers (SIGTERM), check server state before calling stop(). Wrap in try-catch to handle phase errors in signal handlers — an unhandled rejection in a shutdown hook terminates the process ungracefully.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilitysilent
  Sources[3]
• stop · stop-lifecycle-hook-error

  error
  WhenonPreStop or onPostStop extension method throws or rejects
  ThrowsError from the lifecycle method — sets server phase to 'invalid'
  Required handlingExtension methods registered with server.ext('onPreStop') or server.ext('onPostStop') MUST handle their own errors internally. An error thrown from a stop lifecycle hook sets the server phase to 'invalid', preventing future start/stop cycles and leaving the process in an undefined state. Always wrap database disconnection, cache flush, and external cleanup calls in try-catch inside these hooks.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilitysilent
  Sources[3]
• register · register-duplicate-plugin

  error
  Whensame plugin registered twice without once: true option
  ThrowsAssertionError: 'Plugin <name> already registered'
  Required handlingAlways use once: true when there is any chance of duplicate plugin registration (e.g. in tests that share a server instance, or in plugin dependency chains where multiple plugins register the same utility plugin). Without once: true, the second registration throws and aborts the entire startup sequence.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5][6]
• register · register-version-requirement-not-met

  error
  Whenplugin specifies hapi or node version requirements that the current runtime does not satisfy
  ThrowsAssertionError: 'Plugin <name> requires hapi version <x> but found <y>'
  Required handlingWrap server.register() in try-catch and handle version mismatch errors at startup. This error is not recoverable at runtime — the process must be restarted with a compatible hapi or Node.js version. Log the error clearly before exiting.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5]
• register · register-plugin-init-error

  error
  Whenplugin's register() function throws an error or returns a rejected promise
  ThrowsError from plugin initialization — database connection, missing config, authentication setup failure
  Required handlingWrap server.register() in try-catch. Plugin initialization errors (failed DB connections, missing environment variables, invalid config) propagate directly from the plugin's register() function. The server cannot start if any plugin registration fails. Ensure all plugins validate their configuration before performing async operations in their register() function.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5][6]
• auth.test · auth-test-unknown-strategy

  error
  Whenstrategy name passed to auth.test() is not registered on the server
  ThrowsAssertionError: 'Unknown authentication strategy: <name>'
  Required handlingValidate strategy names at startup rather than at request time. Wrap auth.test() calls in try-catch when the strategy name is dynamic (e.g. from config or request parameters). An unknown strategy throws synchronously inside the async function, causing an unhandled rejection if not caught.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[7]
• auth.test · auth-test-authentication-failure

  error
  Whenthe strategy's authenticate() method returns an unauthenticated result (invalid token, missing credentials)
  ThrowsBoom.unauthorized error with the authentication challenge details
  Required handlingWrap server.auth.test() in try-catch. The method throws the full Boom error from the authentication strategy, not a simple boolean. The error contains statusCode, message, and WWW-Authenticate headers. Callers must catch and handle this error to return appropriate responses rather than letting it propagate as an unhandled 500.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[7]
• auth.verify · auth-verify-credentials-invalid

  error
  Whenstrategy's verify() method determines credentials have been revoked, expired, or invalidated
  ThrowsError from the strategy's verify() implementation — typically Boom.unauthorized
  Required handlingWrap server.auth.verify() in try-catch in any handler that re-validates credentials after initial authentication (e.g. WebSocket message handlers, long-polling endpoints). Failure to catch this error leaves the connection open with invalid credentials and causes an unhandled rejection that may crash the process or silently fail depending on the error handler setup.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilitysilent
  Sources[7]
• inject · inject-deprecated-credentials-option

  error
  Whenoptions.credentials passed to server.inject() — removed in hapi 17+, replaced by options.auth
  ThrowsAssertionError: 'options.credentials no longer supported (use options.auth)'
  Required handlingMigrate to options.auth = { strategy: <name>, credentials: <obj> } before calling inject(). The legacy options.credentials shape throws synchronously inside inject's async body, producing an unhandled rejection if the test/integration code does not await + try-catch. A common failure mode is older test suites copied from hapi 16 code that never get updated — every call site silently breaks at runtime, not at type-check time.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5]
• inject · inject-auth-options-malformed

  error
  Whenoptions.auth provided but missing required shape (not an object, or missing .credentials, or missing .strategy)
  ThrowsAssertionError: 'options.auth must be an object' / 'options.auth.credentials is missing' / 'options.auth.strategy is missing'
  Required handlingWrap server.inject() in try-catch when options.auth is constructed dynamically (e.g. from a test factory or a stored mock credentials object). All three asserts fire BEFORE any request lifecycle code runs, so the failure is purely a config shape issue — but it produces a synchronous throw inside the async function that becomes an unhandled promise rejection if uncaught. Validate the auth object shape at the call site, or normalize through a typed helper that asserts the shape before passing to inject().
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5]
• inject · inject-handler-throws-boom-error

  error
  Whenroute handler throws (or returns a rejected promise) during the simulated request, OR request processing fails inside hapi internals (validation, auth, pre-handlers)
  ThrowsBoom error (the partial ServerInjectResponse is exposed on .data per official docs). Custom handler errors are rethrown via `throw custom.error` in lib/server.js line 351-352.
  Required handlingWrap server.inject() in try-catch in test and adapter code paths. Unlike the live HTTP server (which sends a 500 response to the client), inject() rethrows the handler's error to the caller. Serverless adapters (Lambda, Cloud Functions) that translate cloud-event payloads through inject() will crash the function invocation and trigger a retry storm if the underlying handler error is not caught and translated into a domain-appropriate response. Tests that don't catch this end up as unhandled promise rejections that crash the test runner instead of failing the specific assertion. The error.data property carries the partial response (status code reached, headers set) — useful for diagnostic logging.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5][8]

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.