chenhg5/cc-connect · error

discord: timed out waiting for Ready event

Error message

discord: timed out waiting for Ready event

What it means

RegisterCommands needs the discordgo application ID, which is only populated after the gateway delivers the Ready event. The method blocks on p.readyCh with a 15-second timeout; if Ready has not arrived in that window it returns this error instead of registering with a zero app ID. It typically means the gateway never finished connecting.

Source

Thrown at platform/discord/discord.go:471

	thread, err := ops.StartStandaloneThread(parentChannelID, freshThreadName(title), threadType, 1440)
	if err != nil {
		return "", replyContext{}, fmt.Errorf("start thread in channel %s: %w", parentChannelID, err)
	}
	if err := ops.JoinThread(thread.ID); err != nil {
		slog.Debug("discord: join fresh thread failed", "thread", thread.ID, "error", err)
	}

	rc := replyContext{channelID: thread.ID, threadID: thread.ID}
	return buildThreadSessionKey(thread.ID), rc, nil
}

// RegisterCommands registers bot commands with Discord for the slash command menu.
func (p *Platform) RegisterCommands(commands []core.BotCommandInfo) error {
	// Wait for Ready event to ensure appID is populated
	select {
	case <-p.readyCh:
	case <-time.After(15 * time.Second):
		return fmt.Errorf("discord: timed out waiting for Ready event")
	}

	var cmds []*discordgo.ApplicationCommand
	for _, c := range commands {
		if len(c.Command) > 32 {
			slog.Warn("discord: command name > 32 skip " + c.Command)
			continue
		}
		desc := c.Description
		if runes := []rune(desc); len(runes) > 100 {
			desc = string(runes[:97]) + "..."
		}
		cmds = append(cmds, &discordgo.ApplicationCommand{
			Name:        c.Command,
			Description: desc,
			// A trick to be able to input any args
			Options: []*discordgo.ApplicationCommandOption{
				{

View on GitHub (pinned to 4000b2338a)

Solutions

  1. Verify the bot token is valid — an auth failure prevents Ready entirely.
  2. Ensure Start() is called and given time to connect before RegisterCommands; increase the readiness window if the network is slow.
  3. Check network access to the Discord gateway (wss) and any proxy configuration.
  4. Retry RegisterCommands with backoff after the timeout, or restructure to register commands from the on-Ready callback.
  5. Call cc-connect doctor / check logs for gateway errors (EOF, auth) preceding this timeout.

Example fix

// before
err := platform.RegisterCommands(cmds) // called before gateway ready
// after
if err := platform.Start(handler); err != nil {
    log.Fatal(err)
}
// give the gateway a moment, then register with retry
for i := 0; i < 3; i++ {
    if err := platform.RegisterCommands(cmds); err == nil {
        break
    } else if !strings.Contains(err.Error(), "timed out waiting for Ready") {
        log.Fatal(err)
    }
    time.Sleep(5 * time.Second)
}
Defensive patterns

Strategy: retry

Validate before calling

// before registering, confirm the gateway is up:
select {
case <-p.readyCh:
case <-time.After(20 * time.Second):
    return fmt.Errorf("gateway not ready; check token/network before RegisterCommands")
}

Try / catch

if err := p.RegisterCommands(cmds); err != nil {
    if strings.Contains(err.Error(), "timed out waiting for Ready") {
        time.Sleep(5 * time.Second)
        return p.RegisterCommands(cmds) // bounded retry
    }
    return err
}

Prevention

When it happens

Trigger: Calling RegisterCommands before/while Start() is still opening the gateway, an invalid bot token causing the Ready event to never fire, network/firewall blocking the Discord gateway, or registration attempted after Stop() cancelled the connection.

Common situations: Invalid DISCORD token in config, corporate proxies or firewalls blocking wss://gateway.discord.gg, slow networks exceeding 15s, registering commands immediately at process start before the connection is up, Discord gateway outages.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

Related errors

AI-assisted analysis of chenhg5/cc-connect@4000b2338a (2026-09-06). Data as JSON: /api/errors/04a28cb1a59298d7. Report an issue: GitHub.