Fixing Hugo Shortcode Errors During Azure Static Web Apps Deployment with Github Action

Issue

I recently started using Hugo shortcodes. Everything compiles and runs fine locally:

1
2
3
4
5
6
7
8
9
PS C:\Users\lucashuang\LucasLocalWorkspace\Blogs\lucaslifes> hugo --gc --minify --enableGitInfo
Start building sites …
hugo v0.146.4-985af1c0 windows/amd64

| EN  | ZH-CN
|----|----
| 139 | 72 ...

Total in 2683 ms

However, the build fails when deploying to Azure Static Web Apps via GitHub Actions:

1
2
3
4
5
6
7
8
Start building sites …
hugo v0.124.1-db083b05 linux/amd64

Error: error building site: process: readAndProcessContent:
/github/workspace/content/page/about/index.md:21:1:
failed to extract shortcode: template for shortcode "buymeacoffee" not found
---End of Oryx build logs---
Oryx has failed to build the solution.

Root Cause

Azure Static Web Apps uses Oryx as its default builder.
The Hugo version bundled with Oryx is v0.124.1, but my custom buymeacoffee shortcode relies on features introduced in ≥ v0.146 (specifically named arguments for .Get ).
Because the version is too old, the shortcode cannot be parsed and the build aborts.

Solution: Tell Oryx to Use a Newer Hugo Version

Oryx looks at the environment variable HUGO_VERSION to decide which version to install.
Add it to the existing “Build And Deploy” step in your GitHub Action:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# .github/workflows/azure-static-web-apps.yml
- name: Build And Deploy
  uses: Azure/static-web-apps-deploy@v1
  env:
    HUGO_VERSION: 0.146.4   # ← Instruct Oryx to use this version
  with:
    azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
    action: "upload"
    app_location: "/"
    api_location: ""
    app_build_command: "hugo --gc --minify --enableGitInfo"
    output_location: "public"

Leave the other steps unchanged. Push your code again and the build and deployment should succeed ✅.

Takeaways

The Hugo version bundled with Oryx is outdated.
If your custom shortcodes depend on newer features, pin the Hugo version.
You can switch versions quickly via the HUGO_VERSION environment variable without altering your existing CI/CD pipeline.