---
title: "Validation"
description: "The schema checks the config while you build and again when the server starts, each time with the values that exist at that moment, and you choose what a failure does."
canonical_url: "https://nuxt-safe-runtime-config.onmax.me/guide/validation"
---
# Validation

> The schema checks the config while you build and again when the server starts, each time with the values that exist at that moment, and you choose what a failure does.

Runtime config holds different values at two moments. During the build it holds what `nuxt.config.ts` says. When the built server starts, Nitro replaces each value that has a matching `NUXT_*` environment variable. The module checks both moments, each with the values it can see, so you don't choose when validation runs.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  runtimeConfig: {
    databaseUrl: '', // set by NUXT_DATABASE_URL in production
    port: 3000,
  },
  safeRuntimeConfig: {
    $schema: runtimeConfigSchema,
  },
})
```

<table>
<thead>
  <tr>
    <th>
      Moment
    </th>
    
    <th>
      Values it sees
    </th>
    
    <th>
      What fails
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        nuxt dev
      </code>
      
      , <code>
        nuxt build
      </code>
      
      , <code>
        nuxt generate
      </code>
    </td>
    
    <td>
      <code>
        nuxt.config.ts
      </code>
    </td>
    
    <td>
      A value that is set and wrong. An empty or missing value is listed and left for the server
    </td>
  </tr>
  
  <tr>
    <td>
      Server start, including the prerender server of <code>
        nuxt generate
      </code>
    </td>
    
    <td>
      <code>
        nuxt.config.ts
      </code>
      
       with <code>
        NUXT_*
      </code>
      
       overrides applied
    </td>
    
    <td>
      Any value that doesn't match, missing ones included
    </td>
  </tr>
</tbody>
</table>

## While you build

The module runs your schema library against the `nuxt.config.ts` values during `nuxt dev`, `nuxt build` and `nuxt generate`. A typo such as `port: '3OOO'` stops the build before anything is deployed.

A value that is `undefined` or `''` at build is how Nuxt marks a value the deployment provides, so the build doesn't fail on it. It logs the keys it left for the server instead:

```txt
[safe-runtime-config] Not set at build, checked when the server starts: databaseUrl
```

The build doesn't need production secrets.

### Require every value at build

When CI builds with every production value, make a missing value fail the build too:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  safeRuntimeConfig: {
    $schema: runtimeConfigSchema,
    requireAtBuild: true,
  },
})
```

The server still checks the config when it starts, because the deployment can override any value.

## When the server starts

The module adds a Nitro plugin and a middleware. When the server starts:

1. The plugin reads `useRuntimeConfig()` after Nitro has applied `NUXT_*` overrides, before your own server plugins run.
2. It [converts the strings](https://nuxt-safe-runtime-config.onmax.me/guide/environment-overrides) to the types the schema expects, so `NUXT_PORT=3000` becomes `3000`.
3. It validates the result and writes the validated values back into runtime config. Nuxt then serializes them into the client payload.
4. For each request, the middleware prepares the event's config before your handlers run, so `useSafeRuntimeConfig(event)` returns checked values.

`nuxt generate` starts the same server to prerender pages, so a static site gets this check during the build, with the environment of the build.

Your schema library is not bundled into the server. At build time the module converts an inline `$schema` to JSON Schema, and the server checks it with [@cfworker/json-schema](https://github.com/cfworker/cfworker/tree/main/packages/json-schema), which also runs on edge runtimes. A schema with transforms has no JSON Schema form. [Move it to its own file](https://nuxt-safe-runtime-config.onmax.me/guide/environment-overrides#transform-values-with-a-schema-module) and the server runs it as written.

## When a check fails

`onError` decides what a failure does:

<table>
<thead>
  <tr>
    <th>
      <code>
        onError
      </code>
    </th>
    
    <th>
      While you build
    </th>
    
    <th>
      When the server starts
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        'throw'
      </code>
      
       (default)
    </td>
    
    <td>
      Logs the issues and stops <code>
        nuxt dev
      </code>
      
       or <code>
        nuxt build
      </code>
    </td>
    
    <td>
      Stops the server with a synchronous schema. With an asynchronous schema, or when a request's own config fails, the request fails instead
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        'warn'
      </code>
    </td>
    
    <td>
      Logs the issues and continues
    </td>
    
    <td>
      Logs the issues and continues
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        'ignore'
      </code>
    </td>
    
    <td>
      Continues without logging
    </td>
    
    <td>
      Continues without logging
    </td>
  </tr>
</tbody>
</table>

Keep `'throw'` in CI and production. Use `'warn'` while you migrate an app whose config does not pass yet.

The build check runs your schema library and prints one line per issue:

```txt
[safe-runtime-config] Validation failed!
  1. port: Invalid type: Expected number but received "3OOO"
  2. public.apiBase: Invalid URL: Received "not a url"
```

The server check of an inline schema prints JSON Schema errors, each with a JSON Pointer to the value:

```txt
[safe-runtime-config] Runtime validation failed: #: Property "databaseUrl" does not match schema., #/databaseUrl: String does not match format "uri".
```

A schema module prints in the first format at server start too, because the server runs your library.

## Upgrade from `validateAtBuild` and `validateAtRuntime`

Earlier versions asked you to pick the moment with two booleans. Both still work and log a deprecation warning.

<table>
<thead>
  <tr>
    <th>
      Before
    </th>
    
    <th>
      Now
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        validateAtRuntime: true
      </code>
    </td>
    
    <td>
      Remove it
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        validateAtBuild: true, validateAtRuntime: true
      </code>
    </td>
    
    <td>
      <code>
        requireAtBuild: true
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        validateAtBuild: false, validateAtRuntime: true
      </code>
    </td>
    
    <td>
      Remove both. The build check no longer fails on values the deployment sets
    </td>
  </tr>
  
  <tr>
    <td>
      Neither, build check only
    </td>
    
    <td>
      Nothing to change. The server now checks the config too, and the build no longer fails on empty placeholders
    </td>
  </tr>
</tbody>
</table>


## Sitemap

See the full [sitemap](https://nuxt-safe-runtime-config.onmax.me/sitemap.md) for all pages.
