hasura/graphql-engine · error

cannot create console server: %w

Error message

cannot create console server: %w

What it means

console.Serve builds two HTTP servers (API and console UI) via GetHTTPServer; a failure building the console server (bad address, TLS config) is returned as 'cannot create console server'. Unlike the fatal log path, this error is returned to the caller of Serve.

Source

Thrown at cli/pkg/console/serve.go:38

	DontOpenBrowser bool
	Browser         string
	ConsolePort     string
	APIPort         string
	Address         string

	SignalChanAPIServer     chan os.Signal
	SignalChanConsoleServer chan os.Signal
}

// Server console and API Server.
func Serve(opts *ServeOpts) error {
	var op errors.Op = "console.Serve"
	// get HTTP servers
	apiHTTPServer := opts.APIServer.GetHTTPServer()

	consoleHTTPServer, err := opts.ConsoleServer.GetHTTPServer()
	if err != nil {
		return errors.E(op, fmt.Errorf("cannot create console server: %w", err))
	}

	go func() {
		<-opts.SignalChanAPIServer

		err := apiHTTPServer.Close()
		if err != nil {
			opts.EC.Logger.Debugf("unable to close server running on port %s", opts.APIPort)
		}
	}()

	go func() {
		<-opts.SignalChanConsoleServer

		err := consoleHTTPServer.Close()
		if err != nil {
			opts.EC.Logger.Debugf("unable to close server running on port %s", opts.ConsolePort)
		}

View on GitHub (pinned to 724551b9ae)

Solutions

1. Check the console address/port flags and free the port (lsof -i :9695)
2. Fix or remove console TLS options
3. Use a different --console-port if 9695 is taken
4. Re-run after the conflicting process exits

Example fix

# before
hasura console --console-port 9695   # port in use -> cannot create console server

# after
hasura console --console-port 9696

// Ensure the console port is free
ln, err := net.Listen("tcp", fmt.Sprintf("%s:%s", addr, consolePort))
if err != nil { return fmt.Errorf("console port unavailable: %w", err) }
ln.Close()

if err := consoleServer.Serve(); err != nil {
    if strings.Contains(err.Error(), "cannot create console server") {
        // free the port or pass --console-port with another value
    }
}

When it happens

Trigger: Calling console.Serve (what `hasura console` runs) when ConsoleServer.GetHTTPServer fails — typically an invalid listen address/port or misconfigured TLS material for the console UI server.

Common situations: Console address/port already bound or invalid (typo like 'locahost'); TLS cert/key mismatch on the console server; running two consoles on the same port.

Related errors

• error serving console: %w
• error starting server: %w
• error creating migrate instance: %w
• cannot fetch template: %w
• error reading from file: path: %s :%w

AI-assisted analysis of hasura/graphql-engine@724551b9ae (2026-08-28). Data as JSON: /api/errors/b9aeb614b833fc57. Report an issue: GitHub.