variables unexpectedly defined when creating window with id

Error message

variables {} unexpectedly defined when creating window with id '{}'

What it means

After verifying required args, get_local_window_variables compares the count of provided local variables against the window's expected_args; extra variables not declared as expected args trigger this error listing the unexpected names. Eww windows only accept arguments they declare.

Solutions

Remove the extra key=value pairs from the `eww open` command
Declare the extra arguments via :expected-args in the window definition
Fix typos so each provided argument matches a declared expected arg
Deduplicate arguments in wrapper scripts that build the open command

Example fix

// before
eww open bar idx=0 colour=red   ; colour not in :expected-args
// after
(defwindow bar :expected-args "(idx colour)" ...)
eww open bar idx=0 colour=red

Defensive patterns

Strategy: validation

Validate before calling

const declared = new Set(windowDef.expectedArgs.map(a => a.name));
const extra = Object.keys(providedArgs).filter(k => !declared.has(k));
if (extra.length) throw new Error(`undeclared args: ${extra.join(', ')}`);

Type guard

function onlyDeclaredArgs(def, args) {
  return Object.fromEntries(Object.entries(args).filter(([k]) => def.expectedArgs.some(a => a.name === k)));
}

Try / catch

try { execSync(`eww open ${win} ${args}`); } catch (e) { if (String(e).includes('unexpectedly defined')) { console.error('Remove undeclared args or add them to :expected-args'); } else { throw e; } }

Prevention

Only pass arguments declared in :expected-args
Fix typos in argument names so they match declarations
Update open scripts when window definitions change
Deduplicate key=value pairs in generated open commands

When it happens

Trigger: Calling `eww open <window> extra=...` with keys not present in the window's expected-args (or local_variables built from window defaults plus args), making local_variables.len() exceed expected_args.len().

Common situations: Typos in argument names so they don't match any expected arg; passing args to a window that declares none; stale open scripts after the window definition changed; duplicate args causing count mismatch.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

AI-assisted analysis of elkowar/eww@48f5aa8b37 (2026-09-08). Data as JSON: /api/errors/e85a6b65de92ab02. Report an issue: GitHub.

Appendix: source

Thrown at crates/eww/src/window_arguments.rs:81

            local_variables.insert(VarName::from("id"), DynVal::from(self.instance_id.clone()));
        }
        if self.monitor.is_some() && expected_args.contains(&String::from("screen")) {
            let mon_dyn = DynVal::from(&self.monitor.clone().unwrap());
            local_variables.insert(VarName::from("screen"), mon_dyn);
        }

        local_variables.extend(self.args.clone());

        for attr in &window_def.expected_args {
            let name = VarName::from(attr.name.clone());
            if !local_variables.contains_key(&name) && !attr.optional {
                bail!("Error, missing argument '{}' when creating window with id '{}'", attr.name, self.instance_id);
            }
        }

        if local_variables.len() != window_def.expected_args.len() {
            let unexpected_vars: Vec<_> = local_variables.keys().filter(|&n| !expected_args.contains(&n.0)).cloned().collect();
            bail!(
                "variables {} unexpectedly defined when creating window with id '{}'",
                unexpected_vars.join(", "),
                self.instance_id,
            );
        }

        Ok(local_variables)
    }
}

View on GitHub (pinned to 48f5aa8b37)