m1k1o/neko · error

unknown screen configuration %s

Error message

unknown screen configuration %s

What it means

ChangeScreenSize applies an XRandR screen configuration (size and refresh rate) via XRRSetScreenConfig. If the X server returns a status other than RRSetConfigSuccess, the driver reports 'unknown screen configuration %s' where %s is the requested ScreenSize's string form. It means the requested resolution/rate combination was rejected by the X server.

Source

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

	// convert variables to C types
	c_width, c_height, c_rate := C.int(s.Width), C.int(s.Height), C.short(s.Rate)

	// if screen configuration already exists, just set it
	status := C.XSetScreenConfiguration(c_width, c_height, c_rate)
	if status != C.RRSetConfigSuccess {
		// create new screen configuration
		C.XCreateScreenMode(c_width, c_height, c_rate)

		// screen configuration should exist now, set it
		status = C.XSetScreenConfiguration(c_width, c_height, c_rate)
	}

	var err error

	// if screen configuration was not set successfully, return error
	if status != C.RRSetConfigSuccess {
		err = fmt.Errorf("unknown screen configuration %s", s.String())
	}

	// if specified rate is not supported a BadValue error is returned
	if status == C.BadValue {
		err = fmt.Errorf("unsupported screen rate %d", s.Rate)
	}

	return s, err
}

func GetScreenSize() types.ScreenSize {
	mu.Lock()
	defer mu.Unlock()

	c_width, c_height, c_rate := C.int(0), C.int(0), C.short(0)
	C.XGetScreenConfiguration(&c_width, &c_height, &c_rate)

	return types.ScreenSize{

View on GitHub (pinned to b0f01cedea)

Solutions

1. Query GetScreenSize / XRandR-supported modes first and only request a listed size
2. Fall back to the current configuration when the request fails
3. Verify the X server has XRandR enabled (xrandr -q) and the output is active
4. Update the client's resolution list after display/driver changes

Example fix

// before
_, err := xorg.SetScreenSize(types.ScreenSize{Width: 3840, Height: 2160, Rate: 60})
// after
avail := xorg.GetScreenSizes() // only offer supported modes
if containsSize(avail, want) {
    _, err := xorg.SetScreenSize(want)
} else {
    err = fmt.Errorf("resolution %s not supported", want)
}

// only request sizes the server advertises as supported
sizes := xorg.GetScreenSizes() // or cache from XRandR query
func isSupported(s types.ScreenSize, sizes []types.ScreenSize) bool {
    for _, v := range sizes {
        if v.Width == s.Width && v.Height == s.Height && v.Rate == s.Rate {
            return true
        }
    }
    return false
}

func isScreenConfigRejected(err error) bool {
    return err != nil && strings.Contains(err.Error(), "unknown screen configuration")
}

s, err := xorg.SetScreenSize(want)
if err != nil {
    if isScreenConfigRejected(err) {
        // fall back to current config or nearest supported mode
        cur := xorg.GetScreenSize()
        log.Printf("%v unsupported; keeping %s", err, cur)
        return cur, nil
    }
    return s, err
}

When it happens

Trigger: Requesting a ScreenSize whose width/height is not among the XRandR-supported modes for the output; calling SetScreenSize with values hardcoded from a different machine's display; X server lacking XRandR support on the active output.

Common situations: Remote-control clients offering resolutions the headless/virtual display does not support; VMs or dummy drivers with a limited modelist; stale cached screen-size list after the monitor or driver changed.

Related errors

• unsupported screen rate %d
• unknown touch id %v
• debounced button %v
• debounced key %v

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