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

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.

Related Functions

• wezterm.config_file - Path to your config file
• wezterm.config_dir - Directory containing your config
• wezterm.reload_configuration() - Reload the configuration

Source Reference

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