Jguer/yay · error

init.lua: unknown yay.opt key

Error message

init.lua: unknown yay.opt key: %s

What it means

During Load, the Lua init.lua is executed and any keys set via yay.opt that the engine does not recognize are collected and reported as one error per unknown key, prefixed 'init.lua: unknown yay.opt key: '. This guards against silent no-op configuration caused by typos or removed/renamed options.

Solutions

1. Fix or remove the offending key in init.lua; the key name is given verbatim in the message.
2. Check the current yay.opt option list in the settings/lua package for the correct spelling/renames.
3. If migrating versions, consult the changelog for renamed or removed yay.opt keys.
4. Register the option in the engine's known-keys set if you are extending the tool with a new option.

Example fix

// init.lua with a typo
-- before
yay.opt.searchby = "fuzzy"
-- after
yay.opt.search_by = "fuzzy"  -- actual supported key

// Before loading, scan init.lua for yay.opt assignments and compare with known keys
known := map[string]bool{"search_by": true /* ... */}
for _, key := range extractOptKeys(initLuaSrc) {
    if !known[key] { log.Printf("unknown yay.opt key in init.lua: %s", key) }
}

engine, err := lua.Load(path)
if err != nil {
    if strings.Contains(err.Error(), "unknown yay.opt key") {
        log.Printf("init.lua has stale/typo'd options: %v", err)
    }
    return err
}

When it happens

Trigger: Calling settings/lua Load (or LoadInto) with an init.lua that assigns an unrecognized key, e.g. yay.opt.searchby = ... or a misspelled option like yay.opt.sourcerank; keys removed in newer versions also trigger this.

Common situations: Typo'd option names in init.lua; following outdated documentation or example configs for renamed options; copying config from another tool that has similarly named options.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• exclude must be a table
• exclude entries must be strings
• unknown upgrade exclusion
• skip_menu must be a boolean
• each result must be a table

AI-assisted analysis of Jguer/yay@328f4b4939 (2026-09-07). Data as JSON: /api/errors/3e0f3a9c828276ff. Report an issue: GitHub.

Appendix: source

Thrown at pkg/settings/lua/load.go:35

	engine := NewWithLogger(luaLogger)
	engine.SetSearchDir(filepath.Dir(path))

	if err := engine.L.DoFile(path); err != nil {
		engine.Close()
		return nil, err
	}

	unknown, errs := engine.Apply(cfg)

	if len(unknown) == 0 && len(errs) == 0 {
		return engine, nil
	}

	var joinErrs []error

	for _, key := range unknown {
		joinErrs = append(joinErrs, fmt.Errorf("init.lua: unknown yay.opt key: %s", key))
	}

	for _, err := range errs {
		joinErrs = append(joinErrs, fmt.Errorf("init.lua: %w", err))
	}

	if err := errors.Join(joinErrs...); err != nil {
		engine.Close()
		return nil, err
	}

	return engine, nil
}

// LoadInto applies the yay.opt values from path onto cfg.
func LoadInto(logger *text.Logger, path string, cfg any) error {
	engine, err := Load(logger, path, cfg)
	if engine != nil {

View on GitHub (pinned to 328f4b4939)