What causes "required gstreamer element %s not found" in m1k1o/neko?

Run `gst-inspect-1.0 ` to confirm the element exists; if not, identify which plugin package provides it and install it (e.g., gst-libav for avdec_*, plugins-ugly for x264enc).

m1k1o/neko · error

required gstreamer element %s not found

Error message

required gstreamer element %s not found

What it means

CheckElement looks up a single GStreamer element factory via gst_element_factory_find. If the factory cannot be found, the element does not exist in the installed GStreamer runtime and this error is returned. Unlike CheckPlugins (plugin-level), this checks the specific element level and is invoked by NewVideoPipeline.

Source

Thrown at server/pkg/gst/gst.go:207

	var plugin *C.GstPlugin
	for _, pluginstr := range plugins {
		plugincstr := C.CString(pluginstr)
		plugin = C.gst_registry_find_plugin(registry, plugincstr)
		C.free(unsafe.Pointer(plugincstr))
		if plugin == nil {
			return fmt.Errorf("required gstreamer plugin %s not found", pluginstr)
		}
	}

	return nil
}

func CheckElement(element string) error {
	elementcstr := C.CString(element)
	factory := C.gst_element_factory_find(elementcstr)
	C.free(unsafe.Pointer(elementcstr))
	if factory == nil {
		return fmt.Errorf("required gstreamer element %s not found", element)
	}
	C.gst_object_unref(C.gpointer(factory))
	return nil
}

//export goHandlePipelineBuffer
func goHandlePipelineBuffer(pipelineID C.int, buf C.gpointer, bufLen C.int, duration C.guint64, deltaUnit C.gboolean) {
	defer C.g_free(buf)

	pipelinesLock.Lock()
	pipeline, ok := pipelines[int(pipelineID)]
	pipelinesLock.Unlock()

	if ok {
		pipeline.sample <- types.Sample{
			Data:      C.GoBytes(unsafe.Pointer(buf), bufLen),
			Length:    int(bufLen),
			Timestamp: time.Now(),

View on GitHub (pinned to b0f01cedea)

Solutions

Run `gst-inspect-1.0 <element>` to confirm the element exists; if not, identify which plugin package provides it and install it (e.g., gst-libav for avdec_*, plugins-ugly for x264enc).
For hardware elements, install/configure the vendor runtime (NVIDIA driver + gst-plugins-bad built with nvcodec, VAAPI driver for vaapi elements).
Check that GST_PLUGIN_PATH includes the directory of any custom/vendor-built plugins.
If the element is genuinely unavailable, change the pipeline to use an equivalent available element (e.g., software encoder x264enc instead of nvh264enc).

Example fix

// pipeline before: requires nvh264enc but host has no NVIDIA runtime -> error
pipeline := "appsrc ! videoconvert ! nvh264enc ! h264parse ! rtph264pay"
// after: fall back to software encoder available in plugins-ugly
pipeline := "appsrc ! videoconvert ! x264enc ! h264parse ! rtph264pay"

Defensive patterns

Strategy: validation

Validate before calling

if err := gst.CheckElement("nvh264enc"); err != nil {
    log.Warn().Msg("hardware encoder unavailable, falling back to software")
    element = "x264enc"
}

Try / catch

if err := gst.CheckElement(name); err != nil {
    return nil, fmt.Errorf("cannot build pipeline: %w", err) // decide fallback or abort here, before CreatePipeline
}

Prevention

Check each element with gst.CheckElement (or gst-inspect-1.0) before constructing pipelines.
For hardware elements (nvenc/vaapi), verify driver and vendor runtime availability at boot.
Prefer feature-detection: choose encoder elements based on CheckElement results rather than hardcoding.
Install the specific plugin package that provides the element (e.g., gst-libav, plugins-ugly) in your image.

When it happens

Trigger: Calling NewVideoPipeline whose pipeline requires an element (e.g., nvh264enc, x264enc, vaapih264enc) that gst_element_factory_find cannot resolve on the host — the element's plugin is not installed, or the plugin is installed but the element was built without the needed dependency (e.g., no NVIDIA/CUDA for nvh264enc, no libx264 for x264enc).

Common situations: Using hardware encoder elements (nvh264enc, vaapi) on machines without the GPU driver/vendor runtime; minimal plugin installs where the element lives in an uninstalled plugin package; GStreamer version differences where an element name changed (e.g., avdec_h264 missing without gst-libav).

Related errors

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