{"record":{"id":"da7c5f34ae14c9d9","repo":"gastownhall/beads","slug":"uow-get-proxy-endpoint-w-da7c5f","errorCode":null,"errorMessage":"uow: get proxy endpoint: %w","messagePattern":"uow: get proxy endpoint: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/storage/uow/external_doltserver_provider.go","lineNumber":67,"sourceCode":"\n\tif err := os.MkdirAll(absServerRootDir, config.BeadsDirPerm); err != nil {\n\t\treturn nil, fmt.Errorf(\"uow: creating server root directory: %w\", err)\n\t}\n\n\ttlsConfigName, err := registerExternalTLSConfig(external)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"uow: external TLS: %w\", err)\n\t}\n\n\tep, err := proxy.GetCreateDatabaseProxyServerEndpoint(absServerRootDir, proxy.OpenOpts{\n\t\tBackend:     proxy.BackendExternal,\n\t\tLogFilePath: serverLogFilePath,\n\t\tExternal:    external,\n\t\tIdleTimeout: idleTimeout,\n\t\tPort:        proxyPort,\n\t})\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"uow: get proxy endpoint: %w\", err)\n\t}\n\n\treturn openAndInitSchema(ctx, ep, database, rootUser, rootPassword, tlsConfigName, teamServer, expectedProjectID, applyProviderOptions(opts))\n}\n\nfunc registerExternalTLSConfig(external configfile.ExternalDoltConfig) (string, error) {\n\tif !external.TLSRequired {\n\t\treturn \"\", nil\n\t}\n\ttc, err := external.TLSClientConfig()\n\tif err != nil {\n\t\treturn \"\", err\n\t}\n\tname := \"beads-external-\" + server.ExternalDoltServerID(external)\n\tif err := mysql.RegisterTLSConfig(name, tc); err != nil {\n\t\treturn \"\", fmt.Errorf(\"register TLS config: %w\", err)\n\t}\n\treturn name, nil","sourceCodeStart":49,"sourceCodeEnd":85,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/uow/external_doltserver_provider.go#L49-L85","documentation":"This wraps a failure from proxy.GetCreateDatabaseProxyServerEndpoint, which resolves or starts the local database-proxy server endpoint before the schema is opened. It means the proxy layer could not produce a usable address/endpoint for the external dolt server (startup, port, or local state problem), so the unit-of-work provider cannot be created.","triggerScenarios":"Calling NewExternalDoltServerUOWProvider when the proxy cannot start or resolve its endpoint in absServerRootDir: the chosen proxyPort is already bound or invalid, the external dolt server cannot be reached/launched via proxy.OpenOpts{Backend: proxy.BackendExternal}, or the proxy's local state files in the server root dir are corrupt/locked.","commonSituations":"Another bd or dolt process already holds proxyPort; stale proxy state left over from a crashed run in the server root directory; container/CI environments where binding localhost ports is restricted; the external dolt server hostname/port is wrong so the proxy backend fails.","solutions":["Check what occupies proxyPort (lsof -i :<port>) and pick a free port or stop the conflicting process.","Inspect the proxy/server log file (serverLogFilePath) for the underlying startup error.","Clear stale proxy state under the server root directory and retry.","Confirm the external dolt server host/port in the ExternalDoltConfig is reachable (nc/host:port) before constructing the provider."],"exampleFix":"// before\nprovider, err := uow.NewExternalDoltServerUOWProvider(ctx, rootDir, \"beads\", logPath, ext, \"root\", pw, 3311, 0, false, \"\")\n// after (port already in use)\nlistener, _ := net.Listen(\"tcp\", \":0\")\nfreePort := listener.Addr().(*net.TCPAddr).Port\nlistener.Close()\nprovider, err := uow.NewExternalDoltServerUOWProvider(ctx, rootDir, \"beads\", logPath, ext, \"root\", pw, freePort, 0, false, \"\")","handlingStrategy":"retry","validationCode":"func portFree(port int) bool {\n\tln, err := net.Listen(\"tcp\", fmt.Sprintf(\"127.0.0.1:%d\", port))\n\tif err != nil {\n\t\treturn false\n\t}\n\tln.Close()\n\treturn true\n}","typeGuard":null,"tryCatchPattern":"var provider uow.UnitOfWorkProvider\nerr := backoff.Retry(func() error {\n\tp, err := uow.NewExternalDoltServerUOWProvider(ctx, root, db, logPath, ext, user, pw, port, 0, false, \"\")\n\tif err != nil {\n\t\tif strings.Contains(err.Error(), \"uow: get proxy endpoint:\") {\n\t\t\treturn err // retryable: port contention / transient startup\n\t\t}\n\t\treturn backoff.Permanent(err)\n\t}\n\tprovider = p\n\treturn nil\n})","preventionTips":["Pick proxy ports explicitly and check occupancy at startup.","Clean stale proxy state in the server root dir after crashes.","Read serverLogFilePath when startup fails; it names the root cause.","In CI, avoid fixed ports and use ephemeral ones."],"tags":["proxy","port-binding","dolt","storage"],"backgroundTag":"proxy-endpoint-startup-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}