What causes "capture pipeline already exists" in m1k1o/neko?

Check for this sentinel error with errors.Is and treat it as success (pipeline already running)

ErrCapturePipelineAlreadyExists

ErrCapturePipelineAlreadyExists

Error message

capture pipeline already exists

What it means

ErrCapturePipelineAlreadyExists is a sentinel error returned when creating a capture pipeline (screen/audio streaming pipeline) whose ID already has an active pipeline in the capture manager. It guards against duplicate stream creation for the same source (e.g. the same screen or audio device).

Source

Thrown at server/pkg/types/capture.go:17

package types

import (
	"context"
	"errors"
	"fmt"
	"math"
	"strings"
	"time"

	"github.com/m1k1o/neko/server/pkg/types/codec"

	"github.com/PaesslerAG/gval"
)

var (
	ErrCapturePipelineAlreadyExists = errors.New("capture pipeline already exists")
)

type Sample struct {
	// timing information
	Timestamp time.Time
	Duration  time.Duration
	// metadata
	DeltaUnit bool // this unit cannot be decoded independently.
	// buffer length
	Length int
	// buffer with encoded media
	Data []byte
}

type SampleListener interface {
	WriteSample(Sample)
}

View on GitHub (pinned to b0f01cedea)

Solutions

Check for this sentinel error with errors.Is and treat it as success (pipeline already running)
Stop the existing pipeline before creating a new one with the same ID
Reuse the existing pipeline/stream instead of creating a new one
Serialize/streamline creation calls so the same ID is not created concurrently

Example fix

// before
err := captureMgr.CreatePipeline(streamID, ...)
if err != nil { return err }
// after
err := captureMgr.CreatePipeline(streamID, ...)
if errors.Is(err, types.ErrCapturePipelineAlreadyExists) {
  return nil // already running, reuse
}
if err != nil { return err }

Defensive patterns

Strategy: try-catch

Validate before calling

// check before creating
if _, err := captureMgr.Image(streamID); err == nil {
  // pipeline already running; reuse it
}

Type guard

func pipelineExists(mgr types.CaptureManager, id string) bool {
  _, err := mgr.Image(id)
  return err == nil
}

Try / catch

err := mgr.CreatePipeline(id, ...)
if errors.Is(err, types.ErrCapturePipelineAlreadyExists) {
  // treat as success, reuse existing pipeline
}

Prevention

Track which streams you already started
Use errors.Is against the sentinel error instead of string matching
Reuse existing pipelines instead of stop/recreate cycles
Serialize creation of the same stream ID

When it happens

Trigger: Calling CreatePipeline/start for a stream ID that already has a running pipeline; calling recreatePipelines when the pipeline already exists; concurrent creation of the same stream ID from two requests.

Common situations: Double-start of screencast/audio streaming (e.g. API retried); two browser clients requesting the same capture source without reuse; dev code calling start() manually when the stream is already running.

Related errors

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