{"record":{"id":"4039a2f93b1fdd01","repo":"bytebase/bytebase","slug":"failed-to-start-embedded-postgresql-instance","errorCode":null,"errorMessage":"failed to start embedded PostgreSQL instance","messagePattern":"failed to start embedded PostgreSQL instance","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"backend/resources/postgres/embedded_instance.go","lineNumber":38,"sourceCode":"type EmbeddedInstanceConfig struct {\n\tDataDir      string\n\tPort         int\n\tUser         string\n\tDatabaseName string\n\tSeedData     string\n}\n\n// StartEmbeddedInstance initializes and starts one embedded PostgreSQL process.\n// The returned stopper preserves its data directory.\nfunc StartEmbeddedInstance(ctx context.Context, config EmbeddedInstanceConfig) (func(), error) {\n\tif config.DataDir == \"\" || config.Port <= 0 || config.User == \"\" || config.DatabaseName == \"\" {\n\t\treturn nil, errors.New(\"embedded PostgreSQL instance requires data directory, port, user, and database\")\n\t}\n\tif err := initDB(config.DataDir, config.User); err != nil {\n\t\treturn nil, errors.Wrap(err, \"failed to initialize embedded PostgreSQL instance\")\n\t}\n\tif err := start(config.Port, config.DataDir, true); err != nil {\n\t\treturn nil, errors.Wrap(err, \"failed to start embedded PostgreSQL instance\")\n\t}\n\tstopper := func() {\n\t\tif err := stop(config.DataDir); err != nil {\n\t\t\tslog.Error(\"failed to stop embedded PostgreSQL instance\", log.BBError(err))\n\t\t}\n\t}\n\tif err := setupEmbeddedInstance(ctx, config); err != nil {\n\t\tstopper()\n\t\treturn nil, errors.Wrap(err, \"failed to set up embedded PostgreSQL instance\")\n\t}\n\treturn stopper, nil\n}\n\n// RemoveEmbeddedInstance stops an embedded PostgreSQL process and removes its\n// exact data directory. A missing directory is successful.\nfunc RemoveEmbeddedInstance(dataDir string) error {\n\tif dataDir == \"\" {\n\t\treturn errors.New(\"embedded PostgreSQL instance requires data directory\")","sourceCodeStart":20,"sourceCodeEnd":56,"githubUrl":"https://github.com/bytebase/bytebase/blob/1870550677fe08f0d2a78c07acd27541464eb945/backend/resources/postgres/embedded_instance.go#L20-L56","documentation":"StartEmbeddedInstance failed while starting the PostgreSQL server process (start, i.e. pg_ctl start) after the data directory was successfully initialized. The underlying error is wrapped with this message; the port may be occupied, binaries may be missing, or the postmaster may have died during startup.","triggerScenarios":"start(config.Port, config.DataDir, true) returns an error in StartEmbeddedInstance — port already in use, pg_ctl/postgres binary missing, data directory corrupted, or postmaster failing to become ready in time.","commonSituations":"Another PostgreSQL (or the previous run's leftover instance) already listening on the configured port; stale postmaster.pid in the data directory; version mismatch between binaries and initialized data directory; insufficient shared memory/semaphores limits.","solutions":["Check if the port is occupied (lsof -i :<port> / ss -ltnp) and free it or choose another port.","Remove a stale postmaster.pid from the data directory if no postmaster is running.","Verify postgres/pg_ctl binaries match the data directory's version.","Inspect the PostgreSQL server log in the data directory for the postmaster's failure reason.","Check OS resource limits (shared memory, semaphores) if postmaster dies at startup."],"exampleFix":"// before\nconfig := EmbeddedInstanceConfig{Port: 5432, ...} // occupied\n// after\nconfig := EmbeddedInstanceConfig{Port: 5433, ...} // free port, or stop the conflicting instance","handlingStrategy":"try-catch","validationCode":"// before calling StartEmbeddedInstance\nln, err := net.Listen(\"tcp\", fmt.Sprintf(\"127.0.0.1:%d\", config.Port))\nif err != nil { return fmt.Errorf(\"port %d in use\", config.Port) }\nln.Close()\nif _, err := exec.LookPath(\"pg_ctl\"); err != nil { return errors.New(\"pg_ctl not on PATH\") }\n// remove stale pid file if no process running\nos.Remove(filepath.Join(config.DataDir, \"postmaster.pid\"))","typeGuard":null,"tryCatchPattern":"stopper, err := postgres.StartEmbeddedInstance(ctx, cfg)\nif err != nil {\n    if strings.Contains(err.Error(), \"failed to start\") {\n        // free port, clear stale postmaster.pid, check server log, then retry\n    }\n    return err\n}\ndefer stopper()","preventionTips":["Reserve a dedicated, free port for the embedded instance.","Stop previous instances via the returned stopper before restarting.","Remove stale postmaster.pid files after crashes.","Match binary versions to the initialized data directory.","Check PostgreSQL server logs and OS resource limits on startup failure."],"tags":["postgresql","embedded","startup","port-conflict"],"backgroundTag":"address-already-in-use","analyzedSha":"1870550677fe08f0d2a78c07acd27541464eb945","analyzedAt":"2026-09-06T21:16:13.665Z","contentChangedAt":"2026-09-06T21:16:13.665Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}