What causes "(pipeline error) %s" in m1k1o/neko?

Read the message after '(pipeline error) ' — it is the native GStreamer diagnostic and names the failing element or parse problem.

m1k1o/neko · critical

(pipeline error) %s

Error message

(pipeline error) %s

What it means

CreatePipeline builds a GStreamer pipeline via cgo (gstreamer_pipeline_create). If GStreamer's C layer reports a GError during parsing/linking, the Go wrapper wraps the raw GStreamer message as "(pipeline error) %s". The %s is the native GStreamer diagnostic (parse error, link failure, missing element, etc.).

Source

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

	ctx    *C.GstPipelineCtx
	sample chan types.Sample
}

func CreatePipeline(pipelineStr string) (Pipeline, error) {
	id := atomic.AddInt32(&pSerial, 1)

	pipelineStrUnsafe := C.CString(pipelineStr)
	defer C.free(unsafe.Pointer(pipelineStrUnsafe))

	pipelinesLock.Lock()
	defer pipelinesLock.Unlock()

	var gstError *C.GError
	ctx := C.gstreamer_pipeline_create(pipelineStrUnsafe, C.int(id), &gstError)

	if gstError != nil {
		defer C.g_error_free(gstError)
		return nil, fmt.Errorf("(pipeline error) %s", C.GoString(gstError.message))
	}

	p := &pipeline{
		id: int(id),
		logger: log.With().
			Str("module", "capture").
			Str("submodule", "gstreamer").
			Int("pipeline_id", int(id)).Logger(),
		src:    pipelineStr,
		ctx:    ctx,
		sample: make(chan types.Sample, 4),
	}

	pipelines[p.id] = p
	return p, nil
}

func (p *pipeline) Src() string {

View on GitHub (pinned to b0f01cedea)

Solutions

Read the message after '(pipeline error) ' — it is the native GStreamer diagnostic and names the failing element or parse problem.
Test the identical pipeline string with `gst-launch-1.0 -v <pipeline>` to reproduce and validate the description.
Check that all required GStreamer elements exist: run the library's CheckPlugins/CheckElement or `gst-inspect-1.0 <element>`.
Install missing GStreamer runtime packages (gstreamer1.0-plugins-base/good/bad/ugly, gstreamer1.0-libav) for your platform.
Fix caps/link incompatibilities (e.g., mismatched framerates, formats, or negotiated caps) in the pipeline description.

Example fix

// before
p, err := gst.CreatePipeline("appsrc ! decodebin ! fakesink") // underspecified caps -> link error
// after
p, err := gst.CreatePipeline("appsrc caps=video/x-raw,format=I420 ! videoconvert ! fakesink")

Defensive patterns

Strategy: try-catch

Validate before calling

if err := gst.CheckElement("x264enc"); err != nil {
    return fmt.Errorf("pipeline prerequisites missing: %w", err)
}
// also validate the description with gst-launch-1.0 during CI

Try / catch

p, err := gst.CreatePipeline(desc)
if err != nil {
    if strings.HasPrefix(err.Error(), "(pipeline error)") {
        return fmt.Errorf("gstreamer rejected pipeline %q: %w", desc, err)
    }
    return err
}

Prevention

Test every pipeline description string with `gst-launch-1.0 -v` in CI before shipping.
Run CheckPlugins/CheckElement for all elements a pipeline depends on at startup.
Pin and verify GStreamer plugin package versions in deployment images.
Log the full pipeline description alongside the native GStreamer error for faster diagnosis.

When it happens

Trigger: Any CreatePipeline call where the underlying C.gstreamer_pipeline_create returns a non-nil *C.GError — typically a malformed pipeline description string (gst-launch syntax), referencing elements/plugins that don't exist, or caps/link incompatibilities.

Common situations: Typos in pipeline descriptions passed to NewVideoPipeline/NewAudioPipeline; GStreamer runtime missing or an incomplete install (e.g., gst-plugins-base not installed); version differences where an element was renamed or removed; incompatible caps between elements causing link failure at runtime.

Related errors

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