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

​
Signature

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

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

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

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.
​
set_strict_mode
function
Enable or disable strict mode for the config builder.
config:set_strict_mode(true)

​
Example with Strict Mode

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

​
Validation
feature
Catches typos and invalid options immediately instead of silently ignoring them
​
Stack Traces
feature
Shows exactly where the problem is in your config file, even in helper functions
​
Strict Mode
feature
Optional error promotion prevents WezTerm from starting with invalid configuration
​
Backward Compatible
feature
Works with existing configs - use conditional check for older versions

​
Backward Compatibility

For configs that need to work with both current and older WezTerm versions: 
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

It’s recommended to use wezterm.config_builder() in all new configurations. It helps catch configuration errors early and makes debugging much easier.

​
Source Reference

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