{"record":{"id":"bde33158a340d668","repo":"browsh-org/browsh","slug":"failed-to-connect-to-firefox-s-marionette-within-3","errorCode":null,"errorMessage":"Failed to connect to Firefox's Marionette within 30 seconds","messagePattern":"Failed to connect to Firefox's Marionette within 30 seconds","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"interfacer/src/browsh/firefox.go","lineNumber":230,"sourceCode":"\tconnected := false\n\tslog.Info(\"Attempting to connect to Firefox Marionette\")\n\tstart := time.Now()\n\tfor time.Since(start) < 30*time.Second {\n\t\tconn, err = net.Dial(\"tcp\", \"127.0.0.1:2828\")\n\t\tif err != nil {\n\t\t\tif !strings.Contains(err.Error(), \"refused\") {\n\t\t\t\tShutdown(err)\n\t\t\t} else {\n\t\t\t\ttime.Sleep(10 * time.Millisecond)\n\t\t\t\tcontinue\n\t\t\t}\n\t\t} else {\n\t\t\tconnected = true\n\t\t\tbreak\n\t\t}\n\t}\n\tif !connected {\n\t\tShutdown(errors.New(\"Failed to connect to Firefox's Marionette within 30 seconds\"))\n\t}\n\tmarionette = conn\n\tgo readMarionette()\n\tsendFirefoxCommand(\"WebDriver:NewSession\", map[string]interface{}{})\n}\n\nfunc installWebextension() {\n\tdata, err := browshXpi.ReadFile(\"browsh.xpi\")\n\tif err != nil {\n\t\tShutdown(err)\n\t}\n\tpath := path.Join(os.TempDir(), \"browsh-webext-addon\")\n\tif err := os.WriteFile(path, []byte(data), 0644); err != nil {\n\t\tShutdown(err)\n\t}\n\targs := map[string]interface{}{\"path\": path}\n\tsendFirefoxCommand(\"Addon:Install\", args)\n}","sourceCodeStart":212,"sourceCodeEnd":248,"githubUrl":"https://github.com/browsh-org/browsh/blob/499ef386d45cd1e2b5457dd04887c017f77b7e27/interfacer/src/browsh/firefox.go#L212-L248","documentation":"Browsh controls Firefox over its Marionette/WebDriver port. `firefoxMarionette` retries dialing that port in a loop for up to 30 seconds; if no connection can be established by then, it concludes Firefox never exposed Marionette and calls `Shutdown`. This means Firefox either didn't start, started without `-marionette`, or is unreachable at the configured host/port.","triggerScenarios":"`setupFirefox` or `StartFirefox` calls `firefoxMarionette`; the dial loop never succeeds within 30s — Firefox failed to launch (bad binary/flags), crashed immediately on startup, started too slowly (cold start under load), or Marionette is disabled/bound elsewhere.","commonSituations":"Slow/loaded CI machines where Firefox takes >30s to start; Firefox crashing on launch due to missing X/GTK libs or profile issues; running a Firefox build with Marionette disabled; resource-starved containers hitting startup timeouts.","solutions":["Verify Firefox starts manually with Marionette: run the same command with `-marionette` and check it doesn't crash.","Confirm the Marionette port (default 2828) is free and reachable: `ss -tlnp | grep 2828`.","Retry on a faster/less loaded machine or warm up Firefox before timing-sensitive runs; check for missing shared libraries (`ldd $(which firefox)`).","Inspect the launched Firefox's stderr/logs for immediate crash causes (profile lock, missing libraries, no display)."],"exampleFix":"// before (shell check)\nfirefox --headless  # starts without marionette -> 30s timeout\n// after\nfirefox --headless --marionette  # marionette listens on :2828\nss -tlnp | grep 2828  # confirm listening before running browsh","handlingStrategy":"retry","validationCode":"const net = require('net');\nconst s = net.connect(2828, '127.0.0.1');\ns.on('connect', () => { console.log('marionette up'); s.end(); });\ns.on('error', () => console.error('marionette not listening; firefox may have failed to start'));","typeGuard":null,"tryCatchPattern":"try {\n  startBrowsh();\n} catch (e) {\n  if (/Marionette within 30 seconds/.test(e.message)) {\n    // warm-up retry: give slow machines a chance\n    setTimeout(startBrowsh, 5000);\n  } else { throw e; }\n}","preventionTips":["Verify `firefox --headless --marionette` starts manually before automation.","Confirm port 2828 is open and not firewalled.","Check Firefox can launch in the environment (libs, profile, display).","On slow CI machines, warm up Firefox or reduce startup load."],"tags":["firefox","marionette","timeout","startup"],"backgroundTag":"marionette-connection-timeout","analyzedSha":"499ef386d45cd1e2b5457dd04887c017f77b7e27","analyzedAt":"2026-09-02T19:05:32.228Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T21:17:11.164Z"}