{"record":{"id":"bc9397b75b5556a8","repo":"sipeed/picoclaw","slug":"env-can-only-be-used-with-stdio-transport","errorCode":null,"errorMessage":"--env can only be used with stdio transport","messagePattern":"--env can only be used with stdio transport","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/picoclaw/internal/mcp/add.go","lineNumber":204,"sourceCode":"\tenv, err := parseEnvAssignments(opts.Env)\n\tif err != nil {\n\t\treturn config.MCPServerConfig{}, err\n\t}\n\theaders, err := parseHeaderAssignments(opts.Headers)\n\tif err != nil {\n\t\treturn config.MCPServerConfig{}, err\n\t}\n\n\tserver := config.MCPServerConfig{\n\t\tEnabled:  true,\n\t\tType:     transport,\n\t\tDeferred: opts.Deferred,\n\t}\n\n\tswitch transport {\n\tcase \"http\", \"sse\":\n\t\tif len(env) > 0 {\n\t\t\treturn config.MCPServerConfig{}, fmt.Errorf(\"--env can only be used with stdio transport\")\n\t\t}\n\t\tif strings.TrimSpace(opts.EnvFile) != \"\" {\n\t\t\treturn config.MCPServerConfig{}, fmt.Errorf(\"--env-file can only be used with stdio transport\")\n\t\t}\n\t\tif len(args) > 0 {\n\t\t\treturn config.MCPServerConfig{}, fmt.Errorf(\"%s transport does not accept command arguments\", transport)\n\t\t}\n\t\tparsedURL, err := url.ParseRequestURI(target)\n\t\tif err != nil || parsedURL.Scheme == \"\" || parsedURL.Host == \"\" {\n\t\t\treturn config.MCPServerConfig{}, fmt.Errorf(\"invalid MCP URL %q\", target)\n\t\t}\n\t\tserver.URL = target\n\t\tserver.Headers = headers\n\t\treturn server, nil\n\t}\n\n\tif len(headers) > 0 {\n\t\treturn config.MCPServerConfig{}, fmt.Errorf(\"--header can only be used with http or sse transport\")","sourceCodeStart":186,"sourceCodeEnd":222,"githubUrl":"https://github.com/sipeed/picoclaw/blob/49183d7e8daed0dba89ddbb6fcb60089401d9680/cmd/picoclaw/internal/mcp/add.go#L186-L222","documentation":"For http/sse transports, buildServerConfig rejects any --env/-e assignments: a remote MCP server cannot receive your local environment variables, so mixing them is an error, not a warning. The env list has already been parsed by parseEnvAssignments, so any -e KEY=value present triggers this.","triggerScenarios":"`picoclaw mcp add name https://host/mcp --transport http -e KEY=value` (or -e KEY=value with -t sse).","commonSituations":"Copy-pasting a working stdio add command and switching only the transport; habit of passing API keys via -e.","solutions":["Remove the --env/-e flags for http/sse servers","Send credentials as headers instead: `-H 'Authorization: Bearer <token>'`","If the server truly needs env vars, run it locally with stdio transport"],"exampleFix":"# before\npicoclaw mcp add api https://example.com/mcp -t http -e API_KEY=secret\n# after\npicoclaw mcp add api https://example.com/mcp -t http -H 'Authorization: Bearer secret'","handlingStrategy":"validation","validationCode":"if [ \"$TRANSPORT\" = http ] || [ \"$TRANSPORT\" = sse ]; then [ ${#ENVS[@]:-0} -eq 0 ] || { echo \"--env is stdio-only\"; exit 2; }; fi","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Map transports to allowed flags up front: http/sse -> headers only; stdio -> env/args","Send remote credentials via -H, never -e","Template separate add commands per transport instead of mutating one"],"tags":["mcp","cli","transport","env","validation"],"backgroundTag":null,"analyzedSha":"49183d7e8daed0dba89ddbb6fcb60089401d9680","analyzedAt":"2026-08-15T21:55:41.315Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}