{"record":{"id":"d06a729d4894ae7a","repo":"mvanhorn/last30days-skill","slug":"format-must-be-text-or-json-got-q","errorCode":null,"errorMessage":"format must be 'text' or 'json', got %q","messagePattern":"format must be 'text' or 'json', got %q","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"mcp/internal/tools/preflight.go","lineNumber":83,"sourceCode":"\treturn runArgs\n}\n\nfunc preflightFormatArgument(args map[string]any) (string, error) {\n\traw, ok := args[\"format\"]\n\tif !ok {\n\t\treturn \"text\", nil\n\t}\n\tvalue, ok := raw.(string)\n\tif !ok {\n\t\treturn \"\", errors.New(\"format must be a string\")\n\t}\n\tswitch value {\n\tcase \"\", \"text\":\n\t\treturn \"text\", nil\n\tcase \"json\":\n\t\treturn \"json\", nil\n\tdefault:\n\t\treturn \"\", fmt.Errorf(\"format must be 'text' or 'json', got %q\", value)\n\t}\n}\n","sourceCodeStart":65,"sourceCodeEnd":86,"githubUrl":"https://github.com/mvanhorn/last30days-skill/blob/c7460f6114449ddfe6ea3fc2f23c3d910c0e740c/mcp/internal/tools/preflight.go#L65-L86","documentation":"Thrown by preflightFormatArgument (mcp/internal/tools/preflight.go:83) when the 'preflight' MCP tool is called with a 'format' argument that is a string but not one of the allowed values. The switch accepts \"\" (treated as \"text\"), \"text\", and \"json\"; anything else — \"Text\", \"JSON\", \"md\", \"yaml\" — hits the default case. The error quotes the offending value with %q so the caller sees exactly what the server received. Non-string types are caught earlier by a separate 'format must be a string' error.","triggerScenarios":"Calling the MCP 'preflight' tool with format set to any string other than '', 'text', or 'json' — e.g. {\"format\": \"markdown\"}, {\"format\": \"Json\"} (case-sensitive), or {\"format\": \"txt\"}. Common when an LLM client guesses an output format the tool doesn't offer, or when a script copies a --emit value (like 'compact' or 'html', which belong to the research tool) into preflight's format argument.","commonSituations":"Model-driven MCP clients inventing plausible enum values; reusing the research tool's emit vocabulary ('compact'/'html') on the preflight tool; case mismatches ('JSON' vs 'json'); stale client code written against an older or imagined schema.","solutions":["Pass format: \"json\" or format: \"text\" exactly (lowercase), or omit the argument entirely — omission defaults to \"text\".","If you want structured machine-readable preflight output, use \"json\"; there is no markdown/html option on this tool.","Check for case or whitespace typos in the argument; the comparison is exact and case-sensitive.","If you're a client author, read the tool's inputSchema (declared via mcplib.WithString(\"format\", ...)) instead of hardcoding guesses."],"exampleFix":"// before (MCP tool call)\n{\"name\": \"preflight\", \"arguments\": {\"format\": \"markdown\"}}\n// -> error: format must be 'text' or 'json', got \"markdown\"\n\n// after\n{\"name\": \"preflight\", \"arguments\": {\"format\": \"json\"}}","handlingStrategy":"validation","validationCode":"// Validate before calling the preflight tool.\nfunc normalizePreflightFormat(v any) (string, error) {\n\tif v == nil {\n\t\treturn \"text\", nil\n\t}\n\ts, ok := v.(string)\n\tif !ok {\n\t\treturn \"\", errors.New(\"format must be a string\")\n\t}\n\tswitch s {\n\tcase \"\", \"text\", \"json\":\n\t\treturn s, nil\n\t}\n\treturn \"\", fmt.Errorf(\"unsupported preflight format %q (want text|json)\", s)\n}","typeGuard":"func isPreflightFormat(v any) bool {\n\tswitch v {\n\tcase nil, \"\", \"text\", \"json\":\n\t\treturn true\n\t}\n\treturn false\n}","tryCatchPattern":null,"preventionTips":["Keep the enum in one constant list shared by client and server; never hardcode 'markdown' or other guessed values.","Remember preflight uses format: text|json while research uses emit: compact|html — don't cross the two vocabularies.","Values are case-sensitive; always lowercase.","Read allowed values from the tool's inputSchema instead of inferring them from the description text."],"tags":["go","mcp","validation","enum","arguments"],"backgroundTag":null,"analyzedSha":"c7460f6114449ddfe6ea3fc2f23c3d910c0e740c","analyzedAt":"2026-08-15T03:34:49.540Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}