m1k1o/neko · error

required gstreamer plugin %s not found

Error message

required gstreamer plugin %s not found

What it means

CheckPlugins iterates a list of required GStreamer plugin names and looks each up in the GStreamer registry via gst_registry_find_plugin. If any plugin is absent from the installed GStreamer runtime, it returns this error naming the missing plugin. It is a pre-flight environment check, so the pipeline is never created.

Source

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

	ok := C.gstreamer_pipeline_set_caps_resolution(p.ctx, cBinName, cWidth, cHeight)
	return ok == C.TRUE
}

func (p *pipeline) EmitVideoKeyframe() bool {
	ok := C.gstreamer_pipeline_emit_video_keyframe(p.ctx)
	return ok == C.TRUE
}

// gst-inspect-1.0
func CheckPlugins(plugins []string) error {
	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

View on GitHub (pinned to b0f01cedea)

Solutions

  1. Install the GStreamer plugin set containing the named plugin (Debian/Ubuntu: gstreamer1.0-plugins-base/good/bad/ugly; Fedora: gstreamer1-plugins-*).
  2. Verify with `gst-inspect-1.0 <plugin>` that the plugin is visible to the runtime.
  3. If installed but not found, check GST_PLUGIN_PATH / GST_PLUGIN_SYSTEM_PATH environment variables and fix the plugin search path.
  4. In Docker, rebuild the image installing the full gstreamer plugin packages, not just libgstreamer.

Example fix

// Dockerfile before
RUN apt-get install -y libgstreamer1.0-0
// after
RUN apt-get install -y libgstreamer1.0-0 gstreamer1.0-plugins-base gstreamer1.0-plugins-good gstreamer1.0-plugins-bad
Defensive patterns

Strategy: validation

Validate before calling

for _, p := range []string{"videotestsrc", "x264enc", "rtph264pay"} {
    if err := gst.CheckPlugins([]string{p}); err != nil {
        return fmt.Errorf("environment check failed: %w", err)
    }
}

Try / catch

if err := gst.CheckPlugins(required); err != nil {
    return fmt.Errorf("missing gstreamer runtime: %w", err) // surface plugin name to installer/logs
}

Prevention

When it happens

Trigger: Calling NewVideoPipeline or NewAudioPipeline (both invoke CheckPlugins) on a machine where one of the required GStreamer plugins (e.g., from gst-plugins-base/good/bad) is not installed or GStreamer is not on the plugin search path (GST_PLUGIN_PATH/GST_PLUGIN_SYSTEM_PATH).

Common situations: Fresh servers or Docker images with only gstreamer1.0 core installed, missing -plugins-base/-good/-bad packages; container images built without GStreamer; broken GST_PLUGIN_SYSTEM_PATH pointing to a directory without the plugins; distribution packages that split plugins into many small packages.

Related errors

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