{"record":{"id":"5f70bc1195b45b29","repo":"gastownhall/beads","slug":"auth-token-file-w","errorCode":null,"errorMessage":"--auth-token-file: %w","messagePattern":"--auth-token-file: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/bd/serve.go","lineNumber":237,"sourceCode":"\t\tAllowNonLoopback: serveAllowNonLoopback,\n\t\tInsecureNoAuth:   serveInsecureNoAuth,\n\t\tAllowedHosts:     serveAllowedHosts,\n\t}\n\tif _, err := httpapi.ValidateBindAddr(serveAddr, serveAllowNonLoopback); err != nil {\n\t\treturn cfg, err\n\t}\n\n\ttokenFile := serveAuthTokenFile\n\tif tokenFile == \"\" {\n\t\ttokenFile = os.Getenv(serveTokenFileEnv)\n\t}\n\tif err := httpapi.ValidateAuthPosture(serveAllowNonLoopback, tokenFile != \"\", serveInsecureNoAuth); err != nil {\n\t\treturn cfg, err\n\t}\n\tif tokenFile != \"\" {\n\t\tauth, err := httpapi.NewTokenFileAuth(tokenFile)\n\t\tif err != nil {\n\t\t\treturn cfg, fmt.Errorf(\"--auth-token-file: %w\", err)\n\t\t}\n\t\tcfg.Auth = auth\n\t}\n\n\tfor _, host := range serveAllowedHosts {\n\t\tif err := httpapi.ValidateAllowedHost(host); err != nil {\n\t\t\treturn cfg, err\n\t\t}\n\t}\n\treturn cfg, nil\n}\n\nfunc runServe() error {\n\t// Flag validation first: it depends on nothing about the workspace, so the\n\t// refusal for a bad --addr or an unservable auth posture is the same in\n\t// every mode, and it lands before anything opens a database.\n\topts, err := resolveServeConfig()\n\tif err != nil {","sourceCodeStart":219,"sourceCodeEnd":255,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/cmd/bd/serve.go#L219-L255","documentation":"resolveServeConfig wraps failures from NewTokenFileAuth (reading/validating the --auth-token-file) with an --auth-token-file prefix so the CLI flag is named in the error. Thrown when the token file is missing, unreadable, or contains invalid token content.","triggerScenarios":"Running `bd serve --auth-token-file <path>` where the file does not exist, lacks read permission, is empty/invalid, or when httpapi.ValidateAuthPosture accepts the combination but the token file cannot be materialized into an auth provider.","commonSituations":"Stale path to a token file after restart; systemd/daemon unit pointing at a secret that was rotated or deleted; token file mounted with wrong permissions in containers; typo in the flag value.","solutions":["Verify the token file exists and is readable by the serve process user.","Check the file contains valid token content (non-empty, correct format per NewTokenFileAuth).","Fix permissions (chmod/chown) or point the flag at the correct secret path.","Use errors.As to inspect the wrapped cause from NewTokenFileAuth for the precise read/parse error."],"exampleFix":"// before\ntokPath := flagValue\n// after\nif info, err := os.Stat(tokPath); err != nil || info.IsDir() {\n    return fmt.Errorf(\"--auth-token-file %s not readable\", tokPath)\n}","handlingStrategy":"validation","validationCode":"if info, err := os.Stat(tokenFile); err != nil || info.IsDir() {\n    return fmt.Errorf(\"--auth-token-file %s missing or invalid\", tokenFile)\n}","typeGuard":null,"tryCatchPattern":"cfg, err := resolveServeConfig(...)\nif err != nil {\n    var msg string\n    if strings.Contains(err.Error(), \"--auth-token-file:\") { /* inspect flag value and file */ }\n    _ = msg\n    return err\n}","preventionTips":["Verify the token file path exists and is readable before starting bd serve.","Rotate and deploy secrets with correct ownership for the serve process user.","Keep token file paths absolute to avoid CWD-dependent failures.","Confirm posture flags (--auth-token-file vs insecure/no-auth) are consistent."],"tags":["auth","configuration","serve","token"],"backgroundTag":"invalid-auth-config","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}