sipeed/picoclaw · error

--env-file can only be used with stdio transport

Error message

--env-file can only be used with stdio transport

What it means

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.

Source

Thrown at cmd/picoclaw/internal/mcp/add.go:207

	}
	headers, err := parseHeaderAssignments(opts.Headers)
	if err != nil {
		return config.MCPServerConfig{}, err
	}

	server := config.MCPServerConfig{
		Enabled:  true,
		Type:     transport,
		Deferred: opts.Deferred,
	}

	switch transport {
	case "http", "sse":
		if len(env) > 0 {
			return config.MCPServerConfig{}, fmt.Errorf("--env can only be used with stdio transport")
		}
		if strings.TrimSpace(opts.EnvFile) != "" {
			return config.MCPServerConfig{}, fmt.Errorf("--env-file can only be used with stdio transport")
		}
		if len(args) > 0 {
			return config.MCPServerConfig{}, fmt.Errorf("%s transport does not accept command arguments", transport)
		}
		parsedURL, err := url.ParseRequestURI(target)
		if err != nil || parsedURL.Scheme == "" || parsedURL.Host == "" {
			return config.MCPServerConfig{}, fmt.Errorf("invalid MCP URL %q", target)
		}
		server.URL = target
		server.Headers = headers
		return server, nil
	}

	if len(headers) > 0 {
		return config.MCPServerConfig{}, fmt.Errorf("--header can only be used with http or sse transport")
	}

	if looksLikeRemoteURL(target) {

View on GitHub (pinned to 49183d7e8d)

Solutions

1. Remove --env-file for http/sse servers
2. Move needed values into headers with -H, or into the server-side URL config
3. Switch to stdio transport if a local env file is required

Example fix

# before
picoclaw mcp add api https://example.com/mcp -t http --env-file .env
# after
picoclaw mcp add api https://example.com/mcp -t http -H "X-Api-Key: $(grep KEY .env | cut -d= -f2)"

if [ "$TRANSPORT" = http ] || [ "$TRANSPORT" = sse ]; then [ -z "${ENV_FILE:-}" ] || { echo "--env-file is stdio-only"; exit 2; }; fi

When it happens

Trigger: `picoclaw mcp add name https://host/mcp --transport sse --env-file .env`.

Common situations: Reusing a stdio command template with the transport flipped to http/sse; CI wrappers that always inject --env-file.

Related errors

• --env can only be used with stdio transport
• unsupported transport %q
• %s transport does not accept command arguments
• --header can only be used with http or sse transport
• target %q looks like a remote MCP URL, but transport is %q.

AI-assisted analysis of sipeed/picoclaw@49183d7e8d (2026-08-15). Data as JSON: /api/errors/976f8b2b00b3023b. Report an issue: GitHub.