{"record":{"id":"66d4e84614c4bd5d","repo":"sipeed/picoclaw","slug":"config-validation-failed-w","errorCode":null,"errorMessage":"config validation failed: %w","messagePattern":"config validation failed: %w","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/picoclaw/internal/mcp/helpers.go","lineNumber":160,"sourceCode":"\t\tclone.Tools.MCP.Servers[name] = server\n\t}\n\n\treturn &clone\n}\n\nfunc validateConfigDocument(data []byte) error {\n\tvar instance map[string]any\n\tif err := json.Unmarshal(data, &instance); err != nil {\n\t\treturn fmt.Errorf(\"failed to decode serialized config: %w\", err)\n\t}\n\n\tschema, err := loadMCPConfigSchema()\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to load MCP config schema: %w\", err)\n\t}\n\n\tif err := schema.Validate(instance); err != nil {\n\t\treturn fmt.Errorf(\"config validation failed: %w\", err)\n\t}\n\n\treturn nil\n}\n\nfunc loadMCPConfigSchema() (*jsonschema.Resolved, error) {\n\tmcpConfigSchemaOnce.Do(func() {\n\t\tvar schema jsonschema.Schema\n\t\tif err := json.Unmarshal([]byte(mcpConfigSchemaJSON), &schema); err != nil {\n\t\t\terrMcpConfigSchema = err\n\t\t\treturn\n\t\t}\n\t\tmcpConfigSchema, errMcpConfigSchema = schema.Resolve(nil)\n\t})\n\n\treturn mcpConfigSchema, errMcpConfigSchema\n}\n","sourceCodeStart":142,"sourceCodeEnd":178,"githubUrl":"https://github.com/sipeed/picoclaw/blob/49183d7e8daed0dba89ddbb6fcb60089401d9680/cmd/picoclaw/internal/mcp/helpers.go#L142-L178","documentation":"The normalized config document is validated against the embedded MCP schema before every save (helpers.go:154-161). It fails when a server entry violates the contract: missing `enabled`, having neither `command` nor `url`, containing an unknown property (servers set additionalProperties:false), or a `type` outside stdio/http/sse. Most often reached through `picoclaw mcp edit` saving hand-made changes.","triggerScenarios":"Editing the config to remove enabled:true from a server; deleting both command and url; adding an undocumented key like timeout or cwd inside a server entry; setting type: grpc.","commonSituations":"Porting entries from other tools' MCP config formats (Claude Desktop mcpServers, Claude Code .mcp.json) that allow extra keys; pruning fields too aggressively; typos in key names.","solutions":["Give every server entry \"enabled\" plus exactly one of \"command\" (stdio) or \"url\" (http/sse)","Restrict each server entry to the known keys: enabled, deferred, command, args, env, env_file, type, url, headers","Set \"type\" only to stdio, http, or sse, or omit it"],"exampleFix":"// before\n\"servers\": { \"s\": { \"command\": \"./srv\", \"timeout\": 30 } }\n// after\n\"servers\": { \"s\": { \"enabled\": true, \"command\": \"./srv\" } }","handlingStrategy":"validation","validationCode":"func validServerEntry(s map[string]any) error {\n\tif _, ok := s[\"enabled\"]; !ok {\n\t\treturn fmt.Errorf(\"server entry missing 'enabled'\")\n\t}\n\t_, hasCmd := s[\"command\"]\n\t_, hasURL := s[\"url\"]\n\tif hasCmd == hasURL { // neither or both\n\t\treturn fmt.Errorf(\"server entry needs exactly one of 'command' or 'url'\")\n\t}\n\tif t, ok := s[\"type\"].(string); ok {\n\t\tswitch t {\n\t\tcase \"stdio\", \"http\", \"sse\":\n\t\tdefault:\n\t\t\treturn fmt.Errorf(\"type %q not in stdio/http/sse\", t)\n\t\t}\n\t}\n\treturn nil\n}","typeGuard":null,"tryCatchPattern":"if err := saveCmd.Execute(); err != nil {\n\tif strings.Contains(err.Error(), \"config validation failed\") {\n\t\t// the wrapped jsonschema error names the offending pointer/property;\n\t\t// print it verbatim to locate the bad server entry\n\t\tfmt.Fprintf(os.Stderr, \"%v\\n\", errors.Unwrap(err))\n\t}\n}","preventionTips":["Every server entry: enabled:true plus exactly one of command or url","Do not port extra keys (timeout, cwd, env by other names) from other tools' MCP formats","Prefer `picoclaw mcp add` over hand-editing — it constructs schema-valid entries"],"tags":["config","validation","json-schema","cli"],"backgroundTag":null,"analyzedSha":"49183d7e8daed0dba89ddbb6fcb60089401d9680","analyzedAt":"2026-08-15T21:55:41.315Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}