hasura/graphql-engine · critical

error starting server: %w

Error message

error starting server: %w

What it means

ConsoleServer.Serve builds its net/http server via GetHTTPServer; if that fails (typically TLS cert/key problems when console TLS is configured), the CLI logs 'error starting server' via Logger.Fatal and exits with status 1. This is a fatal startup path, not a per-request error.

Source

Thrown at cli/pkg/console/consoleserver.go:90

	c.Logger.Debugf(
		"rendering console template [%s] with assets [%s]",
		consoleTemplateVersion,
		consoleAssetsVersion,
	)

	consoleServer := &http.Server{
		Addr:    fmt.Sprintf("%s:%s", c.Address, c.Port),
		Handler: c.Router,
	}

	return consoleServer, nil
}

func (c *ConsoleServer) Serve() {
	server, err := c.GetHTTPServer()
	if err != nil {
		c.Logger.Fatal(fmt.Errorf("error starting server: %w", err))
		os.Exit(1)
	}

	go func() {
		err := server.ListenAndServe()
		if err != nil {
			if stderrors.Is(err, http.ErrServerClosed) {
				c.EC.Logger.Infof("server closed on port %s under signal", c.Port)
			} else {
				c.EC.Logger.WithError(err).Errorf("error listening on port %s", c.Port)
			}
		}
	}()

	consoleURL := fmt.Sprintf("http://%s:%s/", c.Address, c.Port)

	if !c.DontOpenBrowser {
		if c.Browser != "" {

View on GitHub (pinned to 724551b9ae)

Solutions

1. Check the console TLS flags: fix cert/key file paths and ensure they're readable
2. Validate the certificate/key pair with openssl (they must match and be valid PEM)
3. Remove the TLS flags if TLS isn't needed
4. Check the bind address/port is available and permitted

Example fix

# before
hasura console --tls-cert ./cert.pem --tls-key ./key.pem  # wrong path -> error starting server

# after
hasura console --tls-cert /etc/ssl/cert.pem --tls-key /etc/ssl/key.pem

// Validate TLS material before serving
if consoleTLS {
    if _, err := tls.LoadX509KeyPair(certFile, keyFile); err != nil {
        return fmt.Errorf("bad console TLS config: %w", err)
    }
}

// Serve logs fatally and exits; guard by pre-validating GetHTTPServer
if _, err := consoleServer.GetHTTPServer(); err != nil {
    return err // graceful handling instead of Fatal+exit
}

When it happens

Trigger: Running `hasura console` with console TLS options (cert/key files) that are missing, unreadable, or invalid, or an address that can't be bound, causing GetHTTPServer to return an error before ListenAndServe.

Common situations: Passing --tls-cert/--tls-key with wrong paths; cert file permissions; leftover TLS flags from a copied script; port privilege issues when binding low ports as non-root.

Related errors

• error serving console: %w
• cannot create console 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/0225c9cf84f27709. Report an issue: GitHub.