{"id":"c40583ff77ec8210","repo":"gohugoio/hugo","slug":"rebuild-called-when-not-in-watch-mode","errorCode":null,"errorMessage":"rebuild called when not in watch mode","messagePattern":"rebuild called when not in watch mode","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"hugolib/hugo_sites_build.go","lineNumber":263,"sourceCode":"\terrorCount := h.Log.LoggCount(logg.LevelError) + loggers.Log().LoggCount(logg.LevelError)\n\tif errorCount > 0 {\n\t\treturn fmt.Errorf(\"logged %d error(s)\", errorCount)\n\t}\n\n\treturn nil\n}\n\n// Build lifecycle methods below.\n// The order listed matches the order of execution.\n\nfunc (h *HugoSites) initSites() error {\n\th.reset()\n\treturn nil\n}\n\nfunc (h *HugoSites) initRebuild(config *BuildCfg) error {\n\tif !h.Configs.Base.Internal.Watch {\n\t\treturn errors.New(\"rebuild called when not in watch mode\")\n\t}\n\n\th.pageTrees.treePagesResources.WalkPrefixRaw(\"\", func(key string, n contentNode) (radix.WalkFlag, contentNode, error) {\n\t\tcnh.resetBuildState(n)\n\t\treturn radix.WalkContinue, nil, nil\n\t})\n\n\tfor _, s := range h.Sites {\n\t\ts.resetBuildState(config.WhatChanged.needsPagesAssembly)\n\t}\n\n\th.reset()\n\th.resetLogs()\n\n\treturn nil\n}\n\n// process prepares the Sites' sources for a full or partial rebuild.","sourceCodeStart":245,"sourceCodeEnd":281,"githubUrl":"https://github.com/gohugoio/hugo/blob/8a468df065a75c1c7cf9f6850f32148746590ea5/hugolib/hugo_sites_build.go#L245-L281","documentation":"initRebuild performs incremental-rebuild bookkeeping (resetting per-page build state, invalidating caches for changed files) and asserts the site config has watch mode enabled. Hitting it means an incremental rebuild path was entered — Build called with events or WhatChanged changes — while `Internal.Watch` is false, which is an internal invariant violation rather than a user config error.","triggerScenarios":"HugoSites.Build invoked with filesystem events or a populated WhatChanged when the configuration wasn't built with watch enabled — typically only reachable from programmatic use of hugolib (tests, tools embedding Hugo) that pass change events without setting the watch flag.","commonSituations":"Developers embedding hugolib and calling Build with BuildCfg changes/events on a non-watch config; a Hugo bug where a rebuild is triggered after the server's watch config was torn down. Normal CLI users should essentially never see this.","solutions":["If embedding hugolib, enable watch in the config (`internal.watch = true` / the equivalent config option) before passing change events to Build.","Alternatively, call a full Build (no events, nil WhatChanged) instead of an incremental rebuild.","If it appears from plain `hugo server` usage, report it as a bug at github.com/gohugoio/hugo with steps to reproduce."],"exampleFix":"// before: embedding hugolib\ncfg := config.New()\n// watch not set\nh.Build(BuildCfg{}, events...)\n\n// after\ncfg.Set(\"internal\", map[string]any{\"watch\": true})\nh.Build(BuildCfg{}, events...)","handlingStrategy":"type-guard","validationCode":"// only call rebuild paths when watching is on\nif !cfg.Watching() {\n    // do a full Build instead of a rebuild\n}","typeGuard":"func canRebuild(cfg *allconfig.Config) bool { return cfg.Internal.Watch }","tryCatchPattern":null,"preventionTips":["Check watch mode before invoking any incremental-rebuild entry point; use full Build otherwise","When embedding Hugo, set the watch config flag explicitly rather than assuming server defaults","Keep one code path per mode: full builds for one-shot runs, event-driven rebuilds only under the watcher"],"tags":["hugo","watch","rebuild","internal","embedding"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}