> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/wezterm/wezterm/llms.txt
> Use this file to discover all available pages before exploring further.

# wezterm.config_builder()

> Create a configuration builder object with enhanced error checking and validation

Returns a config builder object that can be used to define your configuration with improved error checking and validation.

## Signature

```lua theme={null}
function wezterm.config_builder() -> ConfigBuilder
```

## Return Value

Returns a special userdata object that acts like a table but provides enhanced error checking when you assign configuration options.

## Description

The config builder may look like a regular Lua table, but it is a special userdata type that:

* **Validates configuration options** - Warns or errors when you try to set invalid options
* **Provides stack traces** - Shows exactly where in your config file the error occurred
* **Supports strict mode** - Can promote warnings to errors to catch mistakes early

## Basic Usage

```lua theme={null}
local wezterm = require 'wezterm'
local config = wezterm.config_builder()

config.color_scheme = 'Batman'
config.font_size = 12.0

return config
```

## Enhanced Error Reporting

When you make a typo or use an invalid configuration option, the config builder provides detailed context:

### Without config\_builder

```lua theme={null}
local config = {}
config.wrong = true  -- Produces a terse warning
```

Warning output:

```
WARN  wezterm_dynamic::error > `wrong` is not a valid Config field.
```

### With config\_builder

```lua theme={null}
local wezterm = require 'wezterm'
local config = wezterm.config_builder()

function helper(config)
  config.wrong = true  -- Now shows stack trace
end

helper(config)
```

Warning output with stack trace:

```
WARN  wezterm_dynamic::error > `wrong` is not a valid Config field.
WARN  config::lua > Attempted to set invalid config option `wrong` at:
    [1] /path/to/config.lua:5 global helper
    [2] /path/to/config.lua:8
```

## Strict Mode

You can promote warnings to errors using strict mode. This will cause WezTerm to show a configuration error window and use the default config until you resolve the error.

<ParamField path="set_strict_mode" type="function">
  Enable or disable strict mode for the config builder.

  ```lua theme={null}
  config:set_strict_mode(true)
  ```
</ParamField>

### Example with Strict Mode

```lua theme={null}
local wezterm = require 'wezterm'
local config = wezterm.config_builder()

-- Enable strict mode
config:set_strict_mode(true)

-- This will now cause an error instead of just a warning
config.invalid_option = 'value'  -- Error: config validation failed

return config
```

## Benefits

<ResponseField name="Validation" type="feature">
  Catches typos and invalid options immediately instead of silently ignoring them
</ResponseField>

<ResponseField name="Stack Traces" type="feature">
  Shows exactly where the problem is in your config file, even in helper functions
</ResponseField>

<ResponseField name="Strict Mode" type="feature">
  Optional error promotion prevents WezTerm from starting with invalid configuration
</ResponseField>

<ResponseField name="Backward Compatible" type="feature">
  Works with existing configs - use conditional check for older versions
</ResponseField>

## Backward Compatibility

For configs that need to work with both current and older WezTerm versions:

```lua theme={null}
local wezterm = require 'wezterm'

-- Fallback for older versions
local config = {}
if wezterm.config_builder then
  config = wezterm.config_builder()
end

config.color_scheme = 'Batman'

return config
```

## When to Use

<Note>
  It's recommended to use `wezterm.config_builder()` in all new configurations. It helps catch configuration errors early and makes debugging much easier.
</Note>

## Related Functions

* [wezterm.config\_file](/lua/wezterm/overview#core-functions) - Path to your config file
* [wezterm.config\_dir](/lua/wezterm/overview#core-functions) - Directory containing your config
* [wezterm.reload\_configuration()](/lua/wezterm/overview#utility-functions) - Reload the configuration

## Source Reference

Implementation: `config/src/lua.rs:283-298`