{"record":{"id":"5dfe1bce6b5d0bdc","repo":"charmbracelet/crush","slug":"failed-to-load-configuration-v-5dfe1b","errorCode":null,"errorMessage":"failed to load configuration: %v","messagePattern":"failed to load configuration: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"internal/cmd/server.go","lineNumber":42,"sourceCode":"\trootCmd.AddCommand(serverCmd)\n}\n\nvar serverCmd = &cobra.Command{\n\tUse:   \"server\",\n\tShort: \"Start the Crush server\",\n\tRunE: func(cmd *cobra.Command, _ []string) error {\n\t\tdataDir, err := cmd.Flags().GetString(\"data-dir\")\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"failed to get data directory: %v\", err)\n\t\t}\n\t\tdebug, err := cmd.Flags().GetBool(\"debug\")\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"failed to get debug flag: %v\", err)\n\t\t}\n\n\t\tcfg, err := config.Load(config.GlobalWorkspaceDir(), dataDir, debug)\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"failed to load configuration: %v\", err)\n\t\t}\n\n\t\thostURL, err := server.ParseHostURL(serverHost)\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"invalid server host: %v\", err)\n\t\t}\n\n\t\tlogFile := filepath.Join(config.GlobalCacheDir(), \"server-\"+safeHostName(hostURL), \"crush.log\")\n\n\t\tif term.IsTerminal(os.Stderr.Fd()) {\n\t\t\tcrushlog.Setup(logFile, debug, os.Stderr)\n\t\t} else {\n\t\t\tcrushlog.Setup(logFile, debug)\n\t\t}\n\n\t\tsrv := server.NewServer(cfg, hostURL.Scheme, hostURL.Host)\n\t\tsrv.SetLogger(slog.Default())\n\t\tslog.Info(\"Starting Crush server...\", \"addr\", serverHost)","sourceCodeStart":24,"sourceCodeEnd":60,"githubUrl":"https://github.com/charmbracelet/crush/blob/7944b8e52225d8805e31eacbf7ef24856b0dfb7a/internal/cmd/server.go#L24-L60","documentation":"The server command calls config.Load(config.GlobalWorkspaceDir(), dataDir, debug) to read and validate crushrc/crush.json. Any load or validation failure — malformed config syntax, unknown keys, invalid provider/agent definitions, unreadable files — is wrapped as \"failed to load configuration\".","triggerScenarios":"Starting `crush server` with a syntactically invalid crushrc (bash syntax error, unknown builtin arguments), a crush.json failing schema validation, or a config file that cannot be read at GlobalWorkspaceDir()/data-dir.","commonSituations":"Hand-edited crushrc with a typo in a `provider`/`model`/`mcp` builtin; JSON config left in a half-edited state; API keys referenced via env vars that are unset at server start; permissions referencing nonexistent tools.","solutions":["Read the wrapped inner error in the message — it names the exact file and validation problem.","Run `crush schema` output or docs to check your crushrc/crush.json against the expected config structure.","Temporarily rename crush.json/crushrc and start the server with defaults to isolate the offending file.","Fix bash syntax errors by sourcing the crushrc in bash (`bash -n` for a syntax check).","Verify HOME/XDG paths so GlobalWorkspaceDir() points at the directory holding your intended config."],"exampleFix":"// before (crushrc)\nprovider anthropic {\n  modl \"claude-sonnet-4\"   # typo: unknown key\n}\n// after\nprovider anthropic {\n  model \"claude-sonnet-4\"\n}","handlingStrategy":"validation","validationCode":"// syntax-check crushrc and JSON validity before starting the server\nbash -n ~/.config/crush/crushrc && jq empty ~/.config/crush/crush.json 2>/dev/null || echo \"fix config errors first\"","typeGuard":null,"tryCatchPattern":"cfg, err := config.Load(config.GlobalWorkspaceDir(), dataDir, debug)\nif err != nil {\n    return fmt.Errorf(\"failed to load configuration: %v\", err) // read the wrapped cause for file/line\n}","preventionTips":["Run `bash -n` on crushrc and `jq .` on crush.json after every manual edit.","Change one config block at a time and restart the server to isolate failures.","Validate provider/model/MCP names against `crush schema` output.","Ensure required env vars (API keys) are set in the server's environment."],"tags":["config","validation","server"],"backgroundTag":"config-load-failed","analyzedSha":"7944b8e52225d8805e31eacbf7ef24856b0dfb7a","analyzedAt":"2026-08-29T12:48:59.079Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}