What causes "panic(err) — mcp独立服务启动失败" in flipped-aurora/gin-vue-admin?

Find and stop the process holding the port: lsof -i :PORT or ss -ltnp, or change MCP.Addr to a free port

panic(err) — mcp独立服务启动失败

Error message

panic(err) — mcp独立服务启动失败

What it means

The standalone MCP HTTP server failed to bind/listen on the configured address; the code logs 'mcp独立服务启动失败' and then panics so the process exits rather than silently running without a server. server.Start returns the underlying net/http error which is both logged and re-panicked.

Source

Thrown at server/cmd/mcp/main.go:34

	}

	if err := initializeStandaloneLogger(); err != nil {
		panic(err)
	}

	addr := fmt.Sprintf(":%d", global.GVA_CONFIG.MCP.Addr)
	server := mcpTool.NewStreamableHTTPServer()

	logger.Bg().Mod("cli").
		Field("config", configPath).
		Field("addr", addr).
		Field("path", global.GVA_CONFIG.MCP.Path).
		Field("upstream", global.GVA_CONFIG.MCP.UpstreamBaseURL).
		Info("mcp独立服务启动")

	if err := server.Start(addr); err != nil {
		logger.Bg().Mod("cli").Err(err).Error("mcp独立服务启动失败")
		panic(err)
	}
}

View on GitHub (pinned to 3136500ef3)

Solutions

Find and stop the process holding the port: lsof -i :PORT or ss -ltnp, or change MCP.Addr to a free port
Fix the Addr format in config (e.g. ":8888")
Use a non-privileged port or grant the capability (setcap cap_net_bind_service) for ports <1024
Restart the service after resolving

Example fix

// before
mcp:
  addr: ":8888"   # already in use
// after
mcp:
  addr: ":8889"

Defensive patterns

Strategy: retry

Validate before calling

ln, err := net.Listen("tcp", addr); if err != nil { log.Fatalf("port %s unavailable: %v", addr, err) }; ln.Close()

Try / catch

if err := server.Start(addr); err != nil { logger.Bg().Mod("cli").Err(err).Error("mcp独立服务启动失败"); time.Sleep(retryBackoff); /* retry N times or exit */ panic(err) }

Prevention

Use SO_REUSEPORT or a port allocation range instead of a fixed port
Run a pre-start check (ss -ltn) in deployment scripts to catch port conflicts
Avoid single-instance managers double-starting the service (systemd ensures one instance)
Use ports >1024 or grant capabilities when binding privileged ports

When it happens

Trigger: server.Start(addr) fails because the port from GVA_CONFIG.MCP.Addr is already in use, the address is invalid, or the process lacks permission to bind (ports <1024 as non-root).

Common situations: Another instance of the service still running (port conflict); systemd/supervisord double-start; port 80/443 chosen without root capability; config Addr malformed (missing colon or non-numeric port).

Related errors

AI-assisted analysis of flipped-aurora/gin-vue-admin@3136500ef3 (2026-08-31). Data as JSON: /api/errors/fc6989a79404d29d. Report an issue: GitHub.