Fix TemplateRenderError: html/template: "index" is undefined in Gin

This error occurs when Gin tries to render a template name that was never loaded via LoadHTMLGlob or LoadHTMLFiles. It can also happen when the template file exists but contains a syntax error preventing parsing. Fix it by verifying your glob pattern matches the template files and that template names match the filenames used in c.HTML().

Reading the Stack Trace

Here's what each line means:

• html/template.(*Template).ExecuteTemplate(0x0, {0x1029e4f80, 0x140001c40e0}, {0x1028f1e60, 0x5}, {0x102850ea0, 0x14000196040}): The template engine cannot find a template named 'index' in its parsed template set, returning an error.
• main.indexHandler(0x14000226000) /app/handlers/page.go:12 +0x94: The indexHandler at line 12 calls c.HTML with a template name that does not match any loaded template.
• github.com/gin-gonic/gin.(*Context).HTML(0x14000226000, 0xc8, {0x1028f1e60, 0x5}, {0x102850ea0, 0x14000196040}): Gin's HTML method delegates to the template engine which fails to find the named template.

Common Causes

func main() {
	r := gin.Default()
	r.LoadHTMLGlob("templates/*") // only matches top-level files
	// templates are in templates/pages/index.html
	r.GET("/", indexHandler)
}

// File: templates/index.tmpl
// {{define "index.tmpl"}}...{{end}}

func indexHandler(c *gin.Context) {
	c.HTML(200, "index", gin.H{"title": "Home"}) // wrong: should be "index.tmpl"
}

// File: templates/header.html
// {{define "header"}}
// <h1>{{.Title}</h1>  <!-- missing closing braces -->
// {{end}}

The Fix

Use a glob pattern that matches nested template directories. Ensure the template name in c.HTML matches exactly what LoadHTMLGlob registers, which includes the relative path from the glob root. Check template syntax before deploying.

func main() {
	r := gin.Default()
	r.LoadHTMLGlob("templates/*")
	r.GET("/", indexHandler)
}

func indexHandler(c *gin.Context) {
	c.HTML(200, "index", gin.H{"title": "Home"})
}

func main() {
	r := gin.Default()
	r.LoadHTMLGlob("templates/**/*")
	r.GET("/", indexHandler)
}

func indexHandler(c *gin.Context) {
	c.HTML(http.StatusOK, "pages/index.html", gin.H{"title": "Home"})
}

Testing the Fix

package handlers_test

import (
	"net/http"
	"net/http/httptest"
	"os"
	"path/filepath"
	"testing"

	"github.com/gin-gonic/gin"
	"github.com/stretchr/testify/assert"
)

func TestIndexHandler_RendersTemplate(t *testing.T) {
	gin.SetMode(gin.TestMode)

	// Create temp template
	dir := t.TempDir()
	pages := filepath.Join(dir, "pages")
	os.MkdirAll(pages, 0o755)
	os.WriteFile(filepath.Join(pages, "index.html"), []byte(`<h1>{{.title}}</h1>`), 0o644)

	r := gin.New()
	r.LoadHTMLGlob(filepath.Join(dir, "**/*"))
	r.GET("/", func(c *gin.Context) {
		c.HTML(200, "pages/index.html", gin.H{"title": "Test"})
	})

	req := httptest.NewRequest(http.MethodGet, "/", nil)
	w := httptest.NewRecorder()
	r.ServeHTTP(w, req)

	assert.Equal(t, http.StatusOK, w.Code)
	assert.Contains(t, w.Body.String(), "Test")
}

Run your tests:

go test ./handlers/... -v

Pushing Through CI/CD

git checkout -b fix/gin-template-error,git add handlers/page.go main.go,git commit -m "fix: correct template glob pattern and template name in c.HTML",git push origin fix/gin-template-error

Your CI config should look something like this:

name: CI
on:
  pull_request:
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: '1.22'
      - run: go mod download
      - run: go vet ./...
      - run: go test ./... -race -coverprofile=coverage.out
      - run: go build ./...

The Full Manual Process: 18 Steps

Here's every step you just went through to fix this one bug:

1. Notice the error alert or see it in your monitoring tool
2. Open the error dashboard and read the stack trace
3. Identify the file and line number from the stack trace
4. Open your IDE and navigate to the file
5. Read the surrounding code to understand context
6. Reproduce the error locally
7. Identify the root cause
8. Write the fix
9. Run the test suite locally
10. Fix any failing tests
11. Write new tests covering the edge case
12. Run the full test suite again
13. Create a new git branch
14. Commit and push your changes
15. Open a pull request
16. Wait for code review
17. Merge and deploy to production
18. Monitor production to confirm the error is resolved

Total time: 30-60 minutes. For one bug.

go get github.com/bugstack/sdk

import "github.com/bugstack/sdk"

func init() {
  bugstack.Init(os.Getenv("BUGSTACK_API_KEY"))
}

Deploying the Fix (Manual Path)

1. Run go test ./... locally to confirm templates render.
2. Open a pull request with the template path corrections.
3. Wait for CI checks to pass on the PR.
4. Have a teammate review and approve the PR.
5. Merge to main and verify templates render in staging.

Frequently Asked Questions