sipeed/picoclaw · critical

irc server is required

Error message

irc server is required

What it means

Constructor validation error from NewIRCChannel: IRCSettings.Server is empty, so the channel cannot be built. This is a fail-fast config check — the IRC connection has no host to dial. The channel registration for this instance aborts at startup.

Source

Thrown at pkg/channels/irc/irc.go:31

	"github.com/sipeed/picoclaw/pkg/channels"
	"github.com/sipeed/picoclaw/pkg/config"
	"github.com/sipeed/picoclaw/pkg/logger"
)

// IRCChannel implements the Channel interface for IRC servers.
type IRCChannel struct {
	*channels.BaseChannel
	bc     *config.Channel
	config *config.IRCSettings
	conn   *ircevent.Connection
	ctx    context.Context
	cancel context.CancelFunc
}

// NewIRCChannel creates a new IRC channel.
func NewIRCChannel(bc *config.Channel, cfg *config.IRCSettings, messageBus *bus.MessageBus) (*IRCChannel, error) {
	if cfg.Server == "" {
		return nil, fmt.Errorf("irc server is required")
	}
	if cfg.Nick == "" {
		return nil, fmt.Errorf("irc nick is required")
	}

	base := channels.NewBaseChannel("irc", cfg, messageBus, bc.AllowFrom,
		channels.WithMaxMessageLength(400),
		channels.WithGroupTrigger(bc.GroupTrigger),
		channels.WithReasoningChannelID(bc.ReasoningChannelID),
	)

	return &IRCChannel{
		BaseChannel: base,
		bc:          bc,
		config:      cfg,
	}, nil
}

View on GitHub (pinned to 49183d7e8d)

Solutions

1. Set the IRC server including port, e.g. server: "irc.libera.chat:6697" (json key 'server' or env PICOCLAW_CHANNELS_IRC_SERVER).
2. Confirm the settings block is attached to the right channel entry and the key is spelled 'server'.
3. If using env vars, verify they are exported to the process (printenv in the service context).
4. Add a config lint step that rejects empty required fields before deploy.

Example fix

# before
{ "type": "irc", "settings": {} }

# after
{ "type": "irc", "settings": { "server": "irc.libera.chat:6697", "nick": "mybot" } }

if cfg.Server == "" {
    return nil, fmt.Errorf("irc settings incomplete: 'server' is required (e.g. irc.libera.chat:6697)")
}

if _, err := irc.NewIRCChannel(bc, cfg, messageBus); err != nil {
    // fail startup loudly: this error means config, not runtime, is wrong
    log.Fatalf("channel config invalid: %v", err)
}

When it happens

Trigger: A channel entry of type 'irc' is configured without a server value — missing key in config JSON, unset PICOCLAW_CHANNELS_IRC_SERVER env var, or a typo'd key that silently defaults to empty.

Common situations: New deployment with incomplete config; migrating config where the IRC block was dropped; env var renamed or not exported into the service environment; YAML/JSON key mismatch (config reads json/env, not yaml, for server).

Related errors

• irc nick is required
• line channel_secret and channel_access_token are required
• must be in range 1-65535
• invalid WeCom QR generate URL: %w
• invalid WeCom QR query URL: %w

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