{"record":{"id":"f2f8161176045d29","repo":"hasura/graphql-engine","slug":"error-serving-console-w","errorCode":null,"errorMessage":"error serving console: %w","messagePattern":"error serving console: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/commands/console.go","lineNumber":287,"sourceCode":"\tconsoleAssetsVersion := templateProvider.GetAssetsVersion(o.EC.Version)\n\ttemplateVars[\"assetsVersion\"] = consoleAssetsVersion\n\ttemplateVars[\"assetsPath\"] = templateProvider.GetAssetsCDN()\n\n\t// Setup console server\n\to.EC.Logger.Debugf(\n\t\t\"rendering console template [%s] with assets [%s]\",\n\t\tconsoleTemplateVersion,\n\t\tconsoleAssetsVersion,\n\t)\n\n\tconsoleRouter, err := console.BuildConsoleRouter(\n\t\ttemplateProvider,\n\t\tconsoleTemplateVersion,\n\t\to.StaticDir,\n\t\ttemplateVars,\n\t)\n\tif err != nil {\n\t\treturn errors.E(op, fmt.Errorf(\"error serving console: %w\", err))\n\t}\n\n\tconsoleServer := console.NewConsoleServer(&console.NewConsoleServerOpts{\n\t\tLogger:           o.EC.Logger,\n\t\tAPIPort:          o.APIPort,\n\t\tAddress:          o.Address,\n\t\tBrowser:          o.Browser,\n\t\tDontOpenBrowser:  o.DontOpenBrowser,\n\t\tEC:               o.EC,\n\t\tPort:             o.ConsolePort,\n\t\tRouter:           consoleRouter,\n\t\tStaticDir:        o.StaticDir,\n\t\tTemplateProvider: templateProvider,\n\t})\n\n\t// start console and API HTTP Servers\n\tserveOpts := &console.ServeOpts{\n\t\tAPIServer:               apiServer,","sourceCodeStart":269,"sourceCodeEnd":305,"githubUrl":"https://github.com/hasura/graphql-engine/blob/724551b9ae87845594ef0408cff0e50eb6c90dc5/cli/commands/console.go#L269-L305","documentation":"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'.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check that the API port/address configured for the console is free (lsof -i :<port>) and kill stale hasura console processes","Verify network access to the console template provider (or pre-seed the static dir) if offline/behind a proxy","Delete stale static assets/cache for the console and retry so the template is re-downloaded","Run with --api-port/--address on a free interface, and check server reachability if the console proxies to a Hasura server"],"exampleFix":"// before\nhasura console --api-port 8080\n// after (free the port / pick another)\nhasura console --api-port 9695 --address 127.0.0.1","handlingStrategy":"validation","validationCode":"// before launching\nif ln, err := net.Listen(\"tcp\", fmt.Sprintf(\"%s:%d\", address, apiPort)); err != nil { log.Fatal(\"port busy: \", err) } else { ln.Close() }","typeGuard":null,"tryCatchPattern":"if err := consoleCmd.Run(); err != nil {\n    if strings.Contains(err.Error(), \"error serving console\") {\n        // check port availability / template provider reachability, then retry\n    }\n}","preventionTips":["Always run console on a dedicated free port","Pre-warm/cache console static assets in offline environments","Kill stale hasura console processes before starting a new one"],"tags":["hasura","cli","console","server-startup","port-conflict"],"backgroundTag":"server-bind-failed","analyzedSha":"724551b9ae87845594ef0408cff0e50eb6c90dc5","analyzedAt":"2026-08-28T07:32:55.105Z","schemaVersion":2},"datasetVersion":"2026-08-28T11:17:15.048Z"}