What causes "mcp stdio config requires a non-empty 'command' field" in charmbracelet/crush?

Set a non-empty command path in the MCP stdio config

mcp stdio config requires a non-empty 'command' field

Error message

mcp stdio config requires a non-empty 'command' field

What it means

After resolving an MCP stdio command, createTransport validates that it is not empty/whitespace. An empty command means no process could be spawned, so init fails with this fixed message.

Source

Thrown at internal/agent/tools/mcp/init.go:1043

	return err
}

func maybeTimeoutErr(err error, timeout time.Duration) error {
	if errors.Is(err, context.Canceled) {
		return fmt.Errorf("timed out after %s", timeout)
	}
	return err
}

func createTransport(ctx context.Context, cfg *config.ConfigStore, name string, m config.MCPConfig, resolver config.VariableResolver) (mcp.Transport, *mcpoauth.Handler, error) {
	switch m.Type {
	case config.MCPStdio:
		command, err := resolver.ResolveValue(m.Command)
		if err != nil {
			return nil, nil, fmt.Errorf("invalid mcp command: %w", err)
		}
		if strings.TrimSpace(command) == "" {
			return nil, nil, fmt.Errorf("mcp stdio config requires a non-empty 'command' field")
		}
		args, err := m.ResolvedArgs(resolver)
		if err != nil {
			return nil, nil, err
		}
		envs, err := m.ResolvedEnv(resolver)
		if err != nil {
			return nil, nil, err
		}
		cmd := exec.CommandContext(ctx, home.Long(command), args...)
		cmd.Env = append(os.Environ(), envs...)
		// Run the child in its own process group and kill the whole group when
		// the session context is cancelled. A stdio server often spawns its own
		// children (signal-mcp launches signal-cli); os/exec's default
		// cancellation kills only the direct child, orphaning the rest with
		// PPID 1 — production accumulated 15+ such zombies over two days.
		configureStdioProcess(cmd)
		return &mcp.CommandTransport{

View on GitHub (pinned to 7944b8e522)

Solutions

Set a non-empty command path in the MCP stdio config
If the command comes from an env var, ensure it is exported and non-empty before starting
Remove trailing/leading whitespace issues by quoting the value
Use MCPHttp type instead if you actually meant to configure a URL-based server

Example fix

// before
mcp myserver command ''
// after
mcp myserver command 'npx' args '-y' '@modelcontextprotocol/server-filesystem' '/tmp'

Defensive patterns

Strategy: validation

Validate before calling

if strings.TrimSpace(cfg.Command) == "" {
    return errors.New("mcp stdio config requires a non-empty 'command' field")
}

Prevention

Always fill the command field for stdio-type MCP servers
If the command comes from an env var, assert it is non-empty at startup
Validate your crushrc/crush.json mcp entries after editing
Use http type for URL-based servers instead of leaving command blank

When it happens

Trigger: An MCP stdio entry with an empty or whitespace-only 'command' field, or a command whose value resolves (via env substitution) to an empty string.

Common situations: Command stored in an env var that is unset or empty; config placeholder left blank; YAML/Bash quoting accidentally producing an empty string.

Related errors

AI-assisted analysis of charmbracelet/crush@7944b8e522 (2026-08-29). Data as JSON: /api/errors/405ccc2984ac0b4b. Report an issue: GitHub.