What causes "atom %q not found" in wavetermdev/waveterm?

Verify the atom name matches the one created on this RootElem (check for typos)

atom %q not found

Error message

atom %q not found

What it means

SetAtomVal looks up the named atom in the RootElem's Atoms map under atomLock and updates its value. If no atom with that name exists, it returns "atom %q not found". Atoms only exist if they were previously created/registered on this RootElem; they can also be removed via RemoveAtom. GetAtomVal silently returns nil for missing atoms, so this error only surfaces on writes.

Source

Thrown at tsunami/engine/rootelem.go:224

func (r *RootElem) GetAtomVal(name string) any {
	r.atomLock.Lock()
	defer r.atomLock.Unlock()

	atom, ok := r.Atoms[name]
	if !ok {
		return nil
	}
	return atom.GetVal()
}

func (r *RootElem) SetAtomVal(name string, val any) error {
	r.atomLock.Lock()
	defer r.atomLock.Unlock()

	atom, ok := r.Atoms[name]
	if !ok {
		return fmt.Errorf("atom %q not found", name)
	}
	return atom.SetVal(val)
}

func (r *RootElem) RemoveAtom(name string) {
	r.atomLock.Lock()
	defer r.atomLock.Unlock()

	delete(r.Atoms, name)
}

func validateCFunc(cfunc any) error {
	if cfunc == nil {
		return fmt.Errorf("Component function cannot b nil")
	}
	rval := reflect.ValueOf(cfunc)
	if rval.Kind() != reflect.Func {
		return fmt.Errorf("Component function must be a function")

View on GitHub (pinned to a4447c1563)

Solutions

Verify the atom name matches the one created on this RootElem (check for typos)
Ensure the atom-creating code runs before any SetAtomVal call (initialization order)
Guard against RemoveAtom racing with async writes — remove the write when the atom is torn down
Check you are holding the same RootElem instance the atom was registered on

Example fix

// before
err := root.SetAtomVal("curentPath", path) // typo + possibly never created
// after
if root.GetAtomVal("currentPath") == nil {
    root.CreateAtom("currentPath", "") // ensure atom exists first
}
err := root.SetAtomVal("currentPath", path)

Defensive patterns

Strategy: validation

Validate before calling

if root.GetAtomVal("currentPath") == nil {
    return fmt.Errorf("atom %q does not exist; create it before setting", "currentPath")
}

Type guard

func atomExists(r *engine.RootElem, name string) bool { return r.GetAtomVal(name) != nil }

Try / catch

if err := root.SetAtomVal("currentPath", path); err != nil {
    return fmt.Errorf("set atom failed: %w", err) // includes the missing atom name
}

Prevention

Centralize atom names as constants to avoid typos
Create atoms during component initialization, before any handlers can fire
Audit RemoveAtom call sites for async writers that may outlive the atom
Remember GetAtomVal returns nil silently for missing atoms — only writes surface the error

When it happens

Trigger: SetAtomVal("myAtom", v) where "myAtom" was never created on the RootElem, was created on a different RootElem instance, or was deleted by RemoveAtom before the SetAtomVal call.

Common situations: Typo in the atom name; atom creation path not yet executed when an event handler writes it (initialization-order bug); atom removed on component unmount while an async callback still writes it.

Related errors

AI-assisted analysis of wavetermdev/waveterm@a4447c1563 (2026-09-01). Data as JSON: /api/errors/7cbab61d9039da7a. Report an issue: GitHub.