gohugoio/hugo · critical

failed to create resource spec: %w

Error message

failed to create resource spec: %w

What it means

Wrapper error from Deps initialization (deps/deps.go:270-273): while building Hugo's dependency container, resources.NewSpec — which wires up the resource pipeline (file caches, image processing, minification, security/exec config) — failed, and the underlying cause is wrapped with %w. It is fatal to site construction; Hugo cannot build without a resource spec.

Source

Thrown at deps/deps.go:272

	}

	if d.SourceSpec == nil {
		d.SourceSpec = source.NewSourceSpec(d.PathSpec, nil, d.Fs.Source)
	}

	var common *resources.SpecCommon
	if d.ResourceSpec != nil {
		common = d.ResourceSpec.SpecCommon
	}

	d.Cfg.BaseConfig()

	fileCaches := d.Cfg.FileCaches().(filecache.Caches)
	fileCaches.SetResourceFs(d.BaseFs.ResourcesCache)

	resourceSpec, err := resources.NewSpec(d.PathSpec, common, d.WasmDispatchers, fileCaches, d.MemCache, d.BuildState, d.Log, d, d.ExecHelper, d.BuildClosers, d.BuildState)
	if err != nil {
		return fmt.Errorf("failed to create resource spec: %w", err)
	}
	d.ResourceSpec = resourceSpec

	return nil
}

// TODO(bep) rework this to get it in line with how we manage templates.
func (d *Deps) Compile(prototype *Deps) error {
	var err error
	if prototype == nil {

		if err = d.TranslationProvider.NewResource(d); err != nil {
			return err
		}
		return nil
	}

	if err = d.TranslationProvider.CloneResource(d, prototype); err != nil {

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Read the wrapped cause after the colon — it names the real failure (imaging config, cache path, etc.).
2. Validate the [imaging], [caches], and [minify] sections of your site config against the current Hugo docs.
3. Ensure cacheDir and the resources/_gen directory exist and are writable in the build environment (set HUGO_CACHEDIR to a writable path in CI).
4. If the error appeared after a Hugo upgrade, diff your config against the release notes for renamed/removed options.

// Verify workingDir and publishDir exist and config is complete before constructing deps
if cfg.BaseConfig.WorkingDir == "" {
    return errors.New("working dir not set")
}
if _, err := os.Stat(cfg.BaseConfig.WorkingDir); err != nil {
    return fmt.Errorf("invalid working dir: %w", err)
}

d, err := deps.New(cfg)
if err != nil {
    // wrapped: "failed to create resource spec: <cause>" — unwrap for root cause
    return fmt.Errorf("init hugo deps: %w", err)
}

When it happens

Trigger: Any error path inside resources.NewSpec during deps.Init: invalid imaging configuration (bad quality/resample filter/anchor values), file cache setup failure (unwritable or invalid cacheDir/resourceDir), invalid minify or security config, or a broken build/output related setting passed through PathSpec.

Common situations: Misconfigured [imaging] section in hugo.toml (e.g. unknown resampleFilter or anchor); cacheDir pointing to a read-only or nonexistent location (common in CI containers and read-only filesystems); permission errors on resources/_gen; config regressions after upgrading Hugo versions where defaults or validation changed.

Related errors

• failed to init config: %w
• failed to copy resources to vendor dir: %w
• failed to detect target data serialization format
• no Key set in Resource
• resources.PostProcess cannot be used in a deferred template

AI-assisted analysis of gohugoio/hugo@8a468df065 (2026-07-31). Data as JSON: /data/errors/833da15ceafa596b.json. Report an issue: GitHub ↗.