{"record":{"id":"314a19201ac71ef2","repo":"gastownhall/beads","slug":"resolving-dolt-credential-command-w","errorCode":null,"errorMessage":"resolving dolt credential command: %w","messagePattern":"resolving dolt credential command: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/bd/main.go","lineNumber":271,"sourceCode":"func resolveDoltServerConnection(ctx context.Context, beadsDir string, fileCfg *configfile.Config, doltCfg *dolt.Config) error {\n\tdoltCfg.ServerHost = fileCfg.GetDoltServerHost()\n\t// Port 0 is fine here — auto-start will resolve it. Use the shared helper\n\t// rather than DefaultConfig(...).Port: this hand-built doltCfg is handed\n\t// straight to dolt.New, and a port arriving there without its source is\n\t// read as a caller assertion (see ApplyResolvedServerPort).\n\tdolt.ApplyResolvedServerPort(beadsDir, doltCfg)\n\tdoltCfg.ServerSocket = fileCfg.GetDoltServerSocket()\n\t// A configured credential command targets an authenticating gateway server:\n\t// run it for a short-lived token used as the connection username. Fail closed\n\t// — never fall back to the static/root user when a command was configured but\n\t// failed. Server mode only: embedded stores never present a username, so the\n\t// command must not run (or fail) embedded opens even when the env var is set.\n\t// Dolt-only: the gateway credential command mints a Dolt server\n\t// username. IsSharedServerMode() forces ServerMode true with no backend\n\t// guard, so non-Dolt metadata must not try to resolve a server username.\n\tif doltCfg.ServerMode && fileCfg.GetBackend() == configfile.BackendDolt {\n\t\tif _, err := dolt.ApplyGatewayCredential(ctx, fileCfg, doltCfg); err != nil {\n\t\t\treturn fmt.Errorf(\"resolving dolt credential command: %w\", err)\n\t\t}\n\t}\n\tif doltCfg.ServerUser == \"\" {\n\t\tdoltCfg.ServerUser = fileCfg.GetDoltServerUser()\n\t}\n\t// Use the resolved port for credential lookup — metadata.json port\n\t// and runtime port can diverge (e.g., tunnel on 3308 vs local on 3307).\n\tdoltCfg.ServerPassword = fileCfg.GetDoltServerPasswordForPort(doltCfg.ServerPort)\n\tdoltCfg.ServerTLS = fileCfg.GetDoltServerTLS()\n\treturn nil\n}\n\nvar (\n\trunPostRunAutoCommit = maybeAutoCommit\n\trunPostRunAutoBackup = maybeAutoBackup\n\trunPostRunAutoExport = maybeAutoExport\n\trunPostRunAutoPush   = maybeAutoPush\n)","sourceCodeStart":253,"sourceCodeEnd":289,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/cmd/bd/main.go#L253-L289","documentation":"During startup in shared-server mode with the Dolt backend, bd resolves a gateway credential command that mints a Dolt server username (dolt.ApplyGatewayCredential). If that resolution fails, the process aborts with this wrapped error rather than opening a database with unknown credentials.","triggerScenarios":"config.yaml or environment sets a Dolt gateway credential command that fails to execute, is missing from PATH, returns non-zero, or emits unparseable output — encountered while resolving server-mode UOW topology in main.go.","commonSituations":"Credential helper binary not installed or not in PATH; misquoted shell command in config; helper requires cloud credentials (vault token, AWS profile) that are absent/expired; forcing ServerMode via env var on a non-Dolt backend configuration mistake.","solutions":["Run the configured credential command manually and verify it prints a valid username","Check config.yaml gateway credential command for typos and PATH issues","Refresh the external credentials the helper depends on (tokens, cloud profiles)","Ensure backend is dolt (BackendDolt) if ServerMode is enabled, since non-Dolt backends must skip this step"],"exampleFix":"// before (config.yaml)\ndolt:\n  gatewayCredentialCommand: dolt-gw-creds   # not on PATH\n// after\ndolt:\n  gatewayCredentialCommand: /usr/local/bin/dolt-gw-creds  # absolute path","handlingStrategy":"validation","validationCode":"cmd := getConfiguredCredentialCommand() // from config.yaml\nif err := exec.Command(\"sh\", \"-c\", cmd).Run(); err != nil {\n    return fmt.Errorf(\"gateway credential command %q fails: %v\", cmd, err)\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Test the credential command manually after every config change","Use absolute paths for helper binaries","Ensure dependent secrets (tokens, cloud profiles) are present in the environment"],"tags":["dolt","credentials","startup"],"backgroundTag":"credential-command-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}