{"record":{"id":"976f8b2b00b3023b","repo":"sipeed/picoclaw","slug":"env-file-can-only-be-used-with-stdio-transport","errorCode":null,"errorMessage":"--env-file can only be used with stdio transport","messagePattern":"--env-file can only be used with stdio transport","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/picoclaw/internal/mcp/add.go","lineNumber":207,"sourceCode":"\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\")\n\t}\n\n\tif looksLikeRemoteURL(target) {","sourceCodeStart":189,"sourceCodeEnd":225,"githubUrl":"https://github.com/sipeed/picoclaw/blob/49183d7e8daed0dba89ddbb6fcb60089401d9680/cmd/picoclaw/internal/mcp/add.go#L189-L225","documentation":"For http/sse transports, buildServerConfig rejects --env-file for the same reason as --env: environment files only apply to locally spawned stdio servers. The check is on opts.EnvFile being non-blank after TrimSpace, so even a whitespace-only value is ignored but any real path errors out.","triggerScenarios":"`picoclaw mcp add name https://host/mcp --transport sse --env-file .env`.","commonSituations":"Reusing a stdio command template with the transport flipped to http/sse; CI wrappers that always inject --env-file.","solutions":["Remove --env-file for http/sse servers","Move needed values into headers with -H, or into the server-side URL config","Switch to stdio transport if a local env file is required"],"exampleFix":"# before\npicoclaw mcp add api https://example.com/mcp -t http --env-file .env\n# after\npicoclaw mcp add api https://example.com/mcp -t http -H \"X-Api-Key: $(grep KEY .env | cut -d= -f2)\"","handlingStrategy":"validation","validationCode":"if [ \"$TRANSPORT\" = http ] || [ \"$TRANSPORT\" = sse ]; then [ -z \"${ENV_FILE:-}\" ] || { echo \"--env-file is stdio-only\"; exit 2; }; fi","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Do not inject --env-file unconditionally from CI wrappers","Convert env-file values to headers for remote servers","Keep a stdio variant of the command when env files are required"],"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"}