NNicheStackTutorials
HugoVitePressSvelteKitAstroFrontend ToolsStatic HostingSEO & Web VitalsAd Monetization
← All tutorials
Hugo

Hugo Build Failed on Vercel: `hugo: command not found` + 4 Fixes

Vercel Hugo deploy fails with exit 127 or unstyled pages? Set HUGO_VERSION, init git submodules, fix baseURL and output directory.

·11 min read·Hugo
Hugo Build Failed on Vercel: `hugo: command not found` + 4 Fixes cover

Tested on: Vercel dashboard March 2026, Hugo 0.139.4, PaperMod submodule Symptom: Build failed at sh: hugo: command not found then again at exit code 255.

TL;DR

  • Set HUGO_VERSION (use -extended for SCSS) in Vercel env.
  • Run git submodule update --init --recursive for theme submodules.
  • Set HUGO_BASEURL and outputDirectory: public, framework: null.

Error log 1: hugo not installed

sh: line 1: hugo: command not found
Error: Command "hugo --minify" exited with 127

Vercel doesn't ship Hugo by default. Fix — pin version via environment variable.

Vercel Project Settings → Environment Variables:

HUGO_VERSION = 0.139.4

Build command:

hugo --gc --minify

Vercel's build image downloads Hugo binary when HUGO_VERSION is set.

Error log 2: theme submodule empty

Error: module "PaperMod" not found
WARN  skipping template layouts/_default/baseof.html

Forgot submodules in CI.

vercel.json:

{
  "installCommand": "git submodule update --init --recursive"
}

Or in package.json:

"scripts": {
  "postinstall": "git submodule update --init --recursive"
}

Error log 3: wrong output directory

Build Completed but site shows Vercel starter page

Output Directory was public ✓ but Root Directory pointed to /docs by mistake.

Settings → General → Root Directory: blank (repo root) or .

Error log 4: baseURL wrong

WARN  found no layout for "sitemap"
Links point to localhost:1313

Set production baseURL:

baseURL = "https://myblog.vercel.app/"

Override in Vercel env:

HUGO_BASEURL = https://myblog.vercel.app/

Hugo reads HUGO_BASEURL over config file.

Working vercel.json (final)

{
  "buildCommand": "hugo --gc --minify",
  "outputDirectory": "public",
  "installCommand": "git submodule update --init --recursive && npm ci",
  "framework": null
}

framework: null stops Vercel from auto-detecting Next.js in monorepos.

Go extended edition for SCSS

If you use toCSS:

Error: failed to transform resource: TOCSS: failed to transform

Set:

HUGO_VERSION = 0.139.4-extended

Extended binary includes libsass.

Node post-build (PurgeCSS)

Build command:

hugo --gc --minify && npm run purge

Ensure package.json exists at root Vercel builds.

Local mimic

export HUGO_VERSION=0.139.4
hugo --gc --minify

Check deploy logs for Hugo v0.139.4 and green curl to production.

Timeline of my failures

  1. No HUGO_VERSION → 127
  2. Submodule missing → unstyled HTML
  3. baseURL localhost → broken canonicals
  4. Forgot extended → SCSS build fail

This config has been green for 40+ deploys.

FAQ

Why does Vercel say hugo: command not found?

Vercel doesn't include Hugo by default. Set the HUGO_VERSION environment variable and Vercel downloads the matching binary at build time.

Do I need Hugo extended on Vercel?

Yes, if your theme uses SCSS/Sass (toCSS). Set HUGO_VERSION=0.139.4-extended or similar.

Why is my Hugo site unstyled on Vercel?

Usually a missing git submodule (theme not cloned) or wrong Root Directory setting in project config.

Tags: HugoVercelCI/CDDeployment