sipeed/picoclaw · error

invalid --host value: %w

Error message

invalid --host value: %w

What it means

When `picoclaw gateway` gets an explicit --host, resolveGatewayHostOverride normalizes it with netbind.NormalizeHostInput, which parses a comma-separated list of host tokens (IP literals, 'localhost', '*') into canonical form. This error wraps a token-parse failure: the value is not a host form netbind accepts. It fires in RunE before the gateway starts.

Source

Thrown at cmd/picoclaw/internal/gateway/command.go:23

	"os"

	"github.com/spf13/cobra"

	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
	"github.com/sipeed/picoclaw/pkg/config"
	"github.com/sipeed/picoclaw/pkg/gateway"
	"github.com/sipeed/picoclaw/pkg/logger"
	"github.com/sipeed/picoclaw/pkg/netbind"
	"github.com/sipeed/picoclaw/pkg/utils"
)

func resolveGatewayHostOverride(explicit bool, host string) (string, error) {
	if !explicit {
		return "", nil
	}
	normalized, err := netbind.NormalizeHostInput(host)
	if err != nil {
		return "", fmt.Errorf("invalid --host value: %w", err)
	}
	return normalized, nil
}

func NewGatewayCommand() *cobra.Command {
	var debug bool
	var noTruncate bool
	var allowEmpty bool
	var host string

	cmd := &cobra.Command{
		Use:     "gateway",
		Aliases: []string{"g"},
		Short:   "Start picoclaw gateway",
		Args:    cobra.NoArgs,
		PreRunE: func(_ *cobra.Command, _ []string) error {
			if noTruncate && !debug {
				return fmt.Errorf("the --no-truncate option can only be used in conjunction with --debug (-d)")

View on GitHub (pinned to 49183d7e8d)

Solutions

1. Pass bare hosts only, comma-separated: `--host 127.0.0.1,::1`
2. Remove any :port - the gateway port is configured separately
3. Use `--host '*'` or `0.0.0.0` for all interfaces, `localhost` for loopback only
4. Check `picoclaw gateway --help` for the accepted forms on your build

Example fix

# before
picoclaw gateway --host http://0.0.0.0:8080
# after
picoclaw gateway --host 0.0.0.0

if _, err := netbind.NormalizeHostInput(host); err != nil {
    return fmt.Errorf("reject --host %q before gateway start: %w", host, err)
}

func isGatewayHostToken(s string) bool {
    s = strings.TrimSpace(s)
    if s == "" || s == "*" || strings.EqualFold(s, "localhost") {
        return s != ""
    }
    return net.ParseIP(strings.Trim(s, "[]")) != nil
}

host, err := netbind.NormalizeHostInput(raw)
if err != nil {
    // strip scheme/port with a message showing accepted forms; do not start gateway
    return fmt.Errorf("--host accepts IPs, localhost, or '*' (comma-separated): %w", err)
}

When it happens

Trigger: `picoclaw gateway --host 999.1.1.1` (malformed IPv4), `--host ::zz` (bad IPv6), `--host http://0.0.0.0` (scheme included), `--host 127.0.0.1:8080` (port included), or stray commas/empty tokens in the list.

Common situations: Copying a bind address with its port from another tool's config; including a URL scheme; typos; assuming hostnames with paths are accepted.

Related errors

• port cannot be empty
• host cannot be empty
• host list contains an empty entry
• either --every or --cron must be specified
• the --no-truncate option can only be used in conjunction wit

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