hasura/graphql-engine · error

error serving console: %w

Error message

error serving console: %w

What it means

Thrown by the hasura CLI console command when the underlying console template server fails to start or serve. The CLI downloads/serves a versioned console template (templateProvider + consoleTemplateVersion) bound to the API port and address; any failure in provisioning or serving that template is wrapped as 'error serving console'.

Source

Thrown at cli/commands/console.go:287

	consoleAssetsVersion := templateProvider.GetAssetsVersion(o.EC.Version)
	templateVars["assetsVersion"] = consoleAssetsVersion
	templateVars["assetsPath"] = templateProvider.GetAssetsCDN()

	// Setup console server
	o.EC.Logger.Debugf(
		"rendering console template [%s] with assets [%s]",
		consoleTemplateVersion,
		consoleAssetsVersion,
	)

	consoleRouter, err := console.BuildConsoleRouter(
		templateProvider,
		consoleTemplateVersion,
		o.StaticDir,
		templateVars,
	)
	if err != nil {
		return errors.E(op, fmt.Errorf("error serving console: %w", err))
	}

	consoleServer := console.NewConsoleServer(&console.NewConsoleServerOpts{
		Logger:           o.EC.Logger,
		APIPort:          o.APIPort,
		Address:          o.Address,
		Browser:          o.Browser,
		DontOpenBrowser:  o.DontOpenBrowser,
		EC:               o.EC,
		Port:             o.ConsolePort,
		Router:           consoleRouter,
		StaticDir:        o.StaticDir,
		TemplateProvider: templateProvider,
	})

	// start console and API HTTP Servers
	serveOpts := &console.ServeOpts{
		APIServer:               apiServer,

View on GitHub (pinned to 724551b9ae)

Solutions

1. Check that the API port/address configured for the console is free (lsof -i :<port>) and kill stale hasura console processes
2. Verify network access to the console template provider (or pre-seed the static dir) if offline/behind a proxy
3. Delete stale static assets/cache for the console and retry so the template is re-downloaded
4. Run with --api-port/--address on a free interface, and check server reachability if the console proxies to a Hasura server

Example fix

// before
hasura console --api-port 8080
// after (free the port / pick another)
hasura console --api-port 9695 --address 127.0.0.1

// before launching
if ln, err := net.Listen("tcp", fmt.Sprintf("%s:%d", address, apiPort)); err != nil { log.Fatal("port busy: ", err) } else { ln.Close() }

if err := consoleCmd.Run(); err != nil {
    if strings.Contains(err.Error(), "error serving console") {
        // check port availability / template provider reachability, then retry
    }
}

When it happens

Trigger: Running `hasura console` when the template cannot be fetched/served: unreachable template provider (network/CORS), invalid template version, port already in use (o.APIPort/o.Address), or a missing/unreadable StaticDir.

Common situations: Corporate proxy or offline environment blocking console asset download; another process (or a previous hasura console) already listening on the configured port; stale static assets directory with wrong permissions; pinned console template version that no longer resolves.

Related errors

• error starting server: %w
• cannot create console server: %w
• operation failed: %w
• unable to create directory: %w
• generating docs failed: %w

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