What causes "standalone api port is 0" in openimsdk/open-im-server?

Set api.ports in the config to a list of valid positive ports, e.g. [10002]

standalone api port is 0

Error message

standalone api port is 0

What it means

In standalone (non-cluster) mode the API server's port is selected by indexing cfg.API.Api.Ports with the instance index. If the resolved port is <= 0, startRedisServerRegister refuses to register the service with the error 'standalone api port is 0'. A non-positive port can never be a valid listen address, so startup is aborted.

Source

Thrown at cmd/main.go:457

		names = append(names, name)
	}
	return names
}

type serverConfig struct {
	API         config.API
	Share       config.Share
	RedisConfig config.Redis
	Index       config.Index
}

func startRedisServerRegister(ctx context.Context, cfg *serverConfig, client discovery.SvcDiscoveryRegistry, service grpc.ServiceRegistrar) error {
	apiPort, err := datautil.GetElemByIndex(cfg.API.Api.Ports, int(cfg.Index))
	if err != nil {
		return err
	}
	if apiPort <= 0 {
		return errors.New("standalone api port is 0")
	}
	registerIP, err := network.GetRpcRegisterIP(cfg.API.Api.RegisterIP)
	if err != nil {
		return err
	}
	const validTime = time.Second * 10
	dbb := dbbuild.NewBuilder(nil, &cfg.RedisConfig)
	rdb, err := dbb.Redis(ctx)
	if err != nil {
		return err
	}
	gateway := redis.NewStandaloneGatewayRedis(rdb, validTime)
	selfAddr := net.JoinHostPort(registerIP, strconv.Itoa(apiPort))
	inprocess.SetLocalTarget(selfAddr)
	inprocess.SetBroadcastAddress(cfg.Share.Secret, func(ctx context.Context) ([]string, error) {
		address, err := gateway.GetGatewayAddrs(ctx)
		if err != nil {
			return nil, err

View on GitHub (pinned to 175a7bb067)

Solutions

Set api.ports in the config to a list of valid positive ports, e.g. [10002]
Ensure the instance index (cfg.Index) is within range of the ports list
If running multiple instances, provide one port per instance

Example fix

// before (config)
api: { ports: [] }          # resolves to 0
// after
api: { ports: [10002] }     # one valid port per instance

Defensive patterns

Strategy: validation

Validate before calling

ports := cfg.API.Api.Ports
if len(ports) == 0 || cfg.Index >= len(ports) || ports[cfg.Index] <= 0 {
	return fmt.Errorf("standalone api port missing for index %d", cfg.Index)
}

Prevention

Always define one positive port per instance in api.ports for standalone mode
Validate the config at deploy time (ports non-empty and > 0)
Keep instance count <= len(api.ports)

When it happens

Trigger: cfg.Index exceeds the length or maps to no entry of api.ports, or the ports list contains 0/negative values, so datautil.GetElemByIndex returns <=0 and the guard trips.

Common situations: Standalone deployment where api.ports was left empty or as [0] placeholder; running more instances than ports defined; copy-paste config from cluster mode where ports are unused.

Related errors

AI-assisted analysis of openimsdk/open-im-server@175a7bb067 (2026-09-04). Data as JSON: /api/errors/500adbcf91497da4. Report an issue: GitHub.