m1k1o/neko · info

debounced key %v

Error message

debounced key %v

What it means

KeyDown injects an X11 key press and debounces repeats: if the same keysym code is already in debounce_key (pressed recently and not yet released), the call returns 'debounced key %v'. This guards against duplicate keydown injection from autorepeat or retransmission. It is an expected rate-limit rejection.

Source

Thrown at server/pkg/xorg/xorg.go:123

	mu.Lock()
	defer mu.Unlock()

	if _, ok := debounce_button[code]; ok {
		return fmt.Errorf("debounced button %v", code)
	}

	debounce_button[code] = time.Now()

	C.XButton(C.uint(code), C.int(1))
	return nil
}

func KeyDown(code uint32) error {
	mu.Lock()
	defer mu.Unlock()

	if _, ok := debounce_key[code]; ok {
		return fmt.Errorf("debounced key %v", code)
	}

	debounce_key[code] = time.Now()

	C.XKey(C.KeySym(code), C.int(1))
	return nil
}

func ButtonUp(code uint32) error {
	mu.Lock()
	defer mu.Unlock()

	if _, ok := debounce_button[code]; !ok {
		return fmt.Errorf("debounced button %v", code)
	}

	delete(debounce_button, code)

View on GitHub (pinned to b0f01cedea)

Solutions

1. Send KeyUp(code) before the next KeyDown(code) for the same key
2. Disable client-side autorepeat forwarding (only send initial keydown)
3. Filter duplicate keydown events before calling the API
4. Treat the error as benign: the key is already pressed

Example fix

// before
if err := xorg.KeyDown(key); err != nil { return err }
// after
if err := xorg.KeyDown(key); err != nil {
    if strings.Contains(err.Error(), "debounced key") {
        return nil // autorepeat suppressed by server debounce
    }
    return err
}

// track pressed keys; suppress autorepeat duplicates
var pressed = map[uint32]bool{}
func safeKeyDown(code uint32) error {
    if pressed[code] { return nil }
    if err := xorg.KeyDown(code); err != nil { return err }
    pressed[code] = true
    return nil
}

func isDebouncedKey(err error) bool {
    return err != nil && strings.Contains(err.Error(), "debounced key")
}

if err := xorg.KeyDown(code); err != nil && !isDebouncedKey(err) {
    return err // ignore expected debounce rejection
}

When it happens

Trigger: Calling KeyDown(code) twice without KeyUp(code) between; KeyPress handling an OS autorepeat event for a key already held; duplicated delivery of the same keystroke over the network.

Common situations: Holding a key with client-side autorepeat enabled forwarding every repeat to the server; click-spam or key-macro tools issuing rapid repeats; a stale debounce_key entry after a missed KeyUp.

Related errors

• debounced button %v
• unknown touch id %v
• is not the host
• unknown screen configuration %s
• unsupported screen rate %d

AI-assisted analysis of m1k1o/neko@b0f01cedea (2026-09-01). Data as JSON: /api/errors/032248356f613702. Report an issue: GitHub.