{"record":{"id":"f471ce1605b53129","repo":"m1k1o/neko","slug":"timeouted-while-waiting-for-first-image","errorCode":null,"errorMessage":"timeouted while waiting for first image","messagePattern":"timeouted while waiting for first image","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/internal/capture/screencast.go","lineNumber":208,"sourceCode":"\tif err != nil {\n\t\treturn err\n\t}\n\n\tmanager.pipeline.AttachAppsink(\"appsink\")\n\tmanager.pipeline.Play()\n\tmanager.pipelinesCounter.Inc()\n\tmanager.pipelinesActive.Set(1)\n\n\t// get first image\n\tselect {\n\tcase image, ok := <-manager.pipeline.Sample():\n\t\tif !ok {\n\t\t\treturn errors.New(\"unable to get first image\")\n\t\t} else {\n\t\t\tmanager.setImage(image)\n\t\t}\n\tcase <-time.After(1 * time.Second):\n\t\treturn errors.New(\"timeouted while waiting for first image\")\n\t}\n\n\tpipeline := manager.pipeline\n\tmanager.wg.Go(func() {\n\t\tmanager.logger.Debug().Msg(\"started receiving images\")\n\n\t\tfor {\n\t\t\timage, ok := <-pipeline.Sample()\n\t\t\tif !ok {\n\t\t\t\tmanager.logger.Debug().Msg(\"stopped receiving images\")\n\t\t\t\treturn\n\t\t\t}\n\n\t\t\tmanager.setImage(image)\n\t\t}\n\t})\n\n\treturn nil","sourceCodeStart":190,"sourceCodeEnd":226,"githubUrl":"https://github.com/m1k1o/neko/blob/b0f01cedea68893e85a3fd852c0521238c285695/server/internal/capture/screencast.go#L190-L226","documentation":"createPipeline waits up to 1 second (time.After) for the first image on the pipeline's Sample() channel. If no sample arrives within that window, it returns 'timeouted while waiting for first image'. The library uses this bounded wait so a broken/silent capture source cannot block startup forever.","triggerScenarios":"The newly created GStreamer pipeline does not emit any sample within 1 second — slow source startup, encoder stalls, wrong pipeline string, or a device that produces no frames.","commonSituations":"Heavy load or slow machine where the encoder takes >1s to produce the first frame; misconfigured pipeline element (wrong framerate/caps) yielding no samples; headless or locked display where the capture source never emits.","solutions":["Retry start — under load the first frame may simply be slow; consider increasing the 1s timeout in a fork/patch","Validate the GStreamer pipeline string (caps, framerate, encoder) produces samples with gst-launch","Check the display/capture source is actually producing frames (not blank/locked/headless without a capture backend)","Reduce system load or pre-warm the pipeline before the first request"],"exampleFix":"// before\ncase <-time.After(1 * time.Second):\n    return errors.New(\"timeouted while waiting for first image\")\n// after\ncase <-time.After(5 * time.Second): // allow slow sources to emit first frame\n    return errors.New(\"timeouted while waiting for first image\")","handlingStrategy":"retry","validationCode":"// Pre-check: ensure the capture source is alive and system not overloaded before starting.\n// (Library has no pre-check API; treat timeout as retryable.)\nif err := checkCaptureSourceAvailable(); err != nil {\n    return err\n}","typeGuard":null,"tryCatchPattern":"if err := manager.start(); err != nil {\n    if err.Error() == \"timeouted while waiting for first image\" {\n        // slow source: retry with longer overall budget\n        for i := 0; i < 3; i++ {\n            time.Sleep(500 * time.Millisecond)\n            if err = manager.start(); err == nil { break }\n        }\n    }\n    return err\n}","preventionTips":["Increase the 1s first-frame timeout if sources are known to be slow","Verify the GStreamer pipeline produces frames (framerate caps, encoder plugins installed)","Pre-warm the pipeline at server startup rather than on first request","Monitor system load; heavy CPU can delay the first encoded frame beyond 1s"],"tags":["go","gstreamer","timeout","screencast"],"backgroundTag":"first-frame-timeout","analyzedSha":"b0f01cedea68893e85a3fd852c0521238c285695","analyzedAt":"2026-09-01T10:35:56.638Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}