What causes "screencast not enabled" in m1k1o/neko?

Enable screencast in the configuration (and in the client session) before requesting images

screencast not enabled

Error message

screencast not enabled

What it means

ScreencastManagerCtx.start returns this error when manager.enabled is false, i.e. screencast functionality was not enabled in the configuration. The library refuses to build the GStreamer pipeline for a manager that was constructed as disabled. It surfaces when start() (directly or via GetImage's lazy start path) is invoked on a disabled manager.

Source

Thrown at server/internal/capture/screencast.go:155

		return nil, err
	}

	manager.imageMu.Lock()
	defer manager.imageMu.Unlock()

	if manager.image.Data == nil {
		return nil, errors.New("image data not found")
	}

	return manager.image.Data, nil
}

func (manager *ScreencastManagerCtx) start() error {
	manager.mu.Lock()
	defer manager.mu.Unlock()

	if !manager.enabled {
		return errors.New("screencast not enabled")
	}

	err := manager.createPipeline()
	if err != nil {
		return err
	}

	manager.started = true
	return nil
}

func (manager *ScreencastManagerCtx) stop() {
	manager.mu.Lock()
	defer manager.mu.Unlock()

	manager.started = false
	manager.destroyPipeline()
}

View on GitHub (pinned to b0f01cedea)

Solutions

Enable screencast in the configuration (and in the client session) before requesting images
Update the client to request screencast capability when it needs screenshots
If screencast is intentionally disabled, handle this error and return a clear 'not available' state to the user instead of retrying

Example fix

// before
img, err := manager.GetImage()
// after
if !screencastEnabled {
    return errors.New("screencast is disabled in server config")
}
img, err := manager.GetImage()

Defensive patterns

Strategy: validation

Validate before calling

// Check the application-level config that created the manager before use.
if !cfg.Screencast.Enabled {
    return errors.New("screencast is disabled; cannot get image")
}

Try / catch

img, err := manager.GetImage()
if err != nil && err.Error() == "screencast not enabled" {
    return fmt.Errorf("screencast unavailable: %w", err) // do not retry; fix config
}

Prevention

Enable screencast in server config when any client needs screenshots
Check the enabled flag/config before building UI flows that fetch images
Communicate disabled features to clients instead of attempting calls
Keep screencast enablement consistent between server config and client session negotiation

When it happens

Trigger: Calling GetImage()/start() on a ScreencastManagerCtx created with screencast disabled in the server config (screencast not requested/enabled by the client or settings).

Common situations: Client requests a screenshot while the server was launched without screencast enabled; deployments where screencast is turned off for resource reasons; version/config migrations that reset the screencast option to disabled.

Related errors

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