Deploying My Hugo Blowfish Site to Vercel: Key Gotchas

Table of Contents

Deploying a Hugo site with the Blowfish theme to Vercel is great, but a few common issues can pop up. Here’s a very concise guide to the problems I hit and their solutions.

1. Vercel Shows XML or “Unable to Locate Config File”
#

Symptom: Your Vercel deployment either displays an XML feed instead of your site, or the build fails with an error like “Unable to locate config file.”

Cause: You likely pushed only your Hugo public/ (build output) folder to GitHub, or Vercel’s Root Directory setting is incorrect if your Hugo source is in a subfolder of your repository.

Fix:

Push Full Hugo Source: Vercel needs your entire Hugo project source code, not just the public/ folder. Vercel will build the site.
Set Vercel Root Directory: If your Hugo site isn’t at the Git repo root, set Root Directory in Vercel to point to your Hugo project’s subfolder.

2. Incorrect Hugo Version & Theme Errors
#

Symptom: Build errors like function "X" not defined, or theme features (like Blowfish’s image processing) failing. Vercel logs might show an old Hugo version.

Cause: Vercel defaulted to an older Hugo version(0.58.0 when I tried, extremely old one) incompatible with your theme’s requirements.

Fix:

In Vercel Project Settings > Environment Variables, set HUGO_VERSION to your required version (e.g., 0.128.0). Ensure it’s an extended version for SASS/SCSS themes like Blowfish.

3. Blowfish Theme Avatar Display Issues
#

Symptom: Author avatar not showing, or build errors like resources.GetRemote ... unsupported protocol scheme "" related to author.html.

Cause: The theme’s logic in partials/author.html when trying to process a local author image (from assets/) might fall into an incorrect error-handling branch that misuses resources.GetRemote.

Fix (Important Tip Below):

The problematic else block in the theme’s author.html (which incorrectly tried resources.GetRemote .) needs to be modified to gracefully handle cases where the primary image fetch (resources.Get "path/to/avatar.png") fails, perhaps by logging a warning and displaying no image, rather than crashing the build. Replace the code in layouts/partials/author.html with the following:

{{ $disableImageOptimization := .Site.Params.disableImageOptimization | default false }}
<div class="flex author">
  {{ with .Site.Params.Author.image }} {{/* Only proceed if an image path is configured */}}
    {{ $authorImagePath := . }} {{/* Store the configured path */}}
    {{ $authorImage := "" }}

    {{/* Attempt to get the image resource */}}
    {{ if or (strings.HasPrefix $authorImagePath "http:") (strings.HasPrefix $authorImagePath "https:") }}
      {{ $authorImage = resources.GetRemote $authorImagePath }}
    {{ else }}
      {{ $authorImage = resources.Get $authorImagePath }}
    {{ end }}

    {{/* Only process and display if $authorImage is a valid resource */}}
    {{ if $authorImage }}
      {{ if not $disableImageOptimization }}
        {{ $authorImage = $authorImage.Fill "192x192" }}
      {{ end }}
      <img class="!mt-0 !mb-0 h-24 w-24 rounded-full ltr:mr-4 rtl:ml-4" width="96" height="96"
      alt="{{ $.Site.Params.Author.name | default " Author" }}" src="{{ $authorImage.RelPermalink }}" />
    {{ else }}
      {{/*
        OPTIONAL: Log a warning if the image couldn't be loaded.
        This will appear in your 'hugo server' console or Vercel build logs.
      */}}
      {{ warnf "Author image configured at '%s' could not be loaded or processed." $authorImagePath }}
      {{/* Do nothing here, or display a placeholder if you prefer */}}
      {{/* Example placeholder (optional): <div class="!mt-0 !mb-0 h-24 w-24 rounded-full ltr:mr-4 rtl:ml-4 bg-gray-200"></div> */}}
    {{ end }}
  {{ end }} {{/* End of 'with .Site.Params.Author.image' */}}

  <div class="place-self-center">
    {{ with .Site.Params.Author.name | markdownify }}
    <div class="text-[0.6rem] uppercase leading-3 text-neutral-500 dark:text-neutral-400">
      {{ i18n "author.byline_title" | markdownify }}
    </div>
    <div class="font-semibold leading-6 text-neutral-800 dark:text-neutral-300">
      {{ . }}
    </div>
    {{ end }}
    {{ with .Site.Params.Author.bio | markdownify }}
    <div class="text-sm text-neutral-700 dark:text-neutral-400">{{ . }}</div>
    {{ end }}
    <div class="text-2xl sm:text-lg">{{ partialCached "author-links.html" . }}</div>
  </div>
</div>

4. Site Deploys Without CSS or Incorrect Theme Colors
#

Symptom: HTML content loads, but all CSS styling is missing, or a configured colorScheme (e.g., “fire”) isn’t applied on Vercel (even if it works locally).

Fixes:

baseURL in hugo.toml/config.toml: Crucial! Ensure baseURL points to your final Vercel URL (e.g., https://your-name.vercel.app/ or custom domain) before deploying. This is a common cause of broken asset paths.
Case Sensitivity (for colorScheme): Vercel (Linux) is case-sensitive. If your theme file is fire.css but your config is colorScheme = "Fire", it will fail.
- Fix: Use lowercase for colorScheme in params.toml to match the CSS filename (e.g., colorScheme = "fire").

Pro Tip: Modifying Theme Files Correctly
#

Don’t directly edit files inside the themes/blowfish/ folder if it’s a Git submodule. Your Git commits to the main project won’t track these changes directly, and theme updates will overwrite them.

Instead, override theme files:

Copy the specific files in the themes folder (e.g., archetypes, assets, images, layouts, static) to the exact same path in your project’s root folders.
Modify these copied files. Hugo prioritizes files in your project’s root over theme files.

Benefits:

Your customizations are part of your main project’s Git history.
Theme updates won’t erase your changes (though you might need to manually merge theme updates into your overridden files later).
Keeps your theme “clean” for easier updates.