What causes "unsupported VBA project" in qax-os/excelize?

Verify you are passing the actual vbaProject.bin (extracted from the xlsm), not the workbook file itself

unsupported VBA project

Error message

unsupported VBA project

What it means

ErrAddVBAProject is returned by AddVBAProject when the supplied file is not a valid vbaProject.bin OLE compound document. The library checks that the data is at least 8 bytes long and starts with the OLE identifier; if not, the project cannot be embedded in the workbook. This guards against attaching corrupted or wrong-type files.

Solutions

Verify you are passing the actual vbaProject.bin (extracted from the xlsm), not the workbook file itself
Check the byte slice is non-empty and starts with the OLE signature D0 CF 11 E0 A1 B1 1A E1 before calling
Re-download or restore the binary with git-lfs; confirm file size matches the original
Wrap the call with errors.Is(err, excelize.ErrAddVBAProject) and surface a clear message to the user

Example fix

// before
file, _ := os.ReadFile("workbook.xlsm")
f.AddVBAProject(file) // ErrAddVBAProject
// after
file, _ := os.ReadFile("vbaProject.bin")
if len(file) >= 8 && bytes.Equal(file[:8], []byte{0xD0, 0xCF, 0x11, 0xE0, 0xA1, 0xB1, 0x1A, 0xE1}) {
    f.AddVBAProject(file)
}

Defensive patterns

Strategy: validation

Validate before calling

func isOLEBinary(data []byte) bool {
    return len(data) >= 8 && bytes.Equal(data[:8], []byte{0xD0, 0xCF, 0x11, 0xE0, 0xA1, 0xB1, 0x1A, 0xE1})
}
// call: if !isOLEBinary(vbaBin) { return errors.New("not a valid vbaProject.bin") }

Type guard

func isValidVBAProject(b []byte) bool { return len(b) >= 8 && bytes.Equal(b[:8], oleIdentifierBytes) }

Prevention

Always read vbaProject.bin itself, never the containing xlsm
Check the read error and length from os.ReadFile before use
Verify the OLE magic bytes D0 CF 11 E0 A1 B1 1A E1
Store binaries with git-lfs and avoid line-ending normalization

When it happens

Trigger: Calling AddVBAProject with a file shorter than 8 bytes, a file whose first 8 bytes do not match the OLE compound-document identifier (oleIdentifier), a text/JSON placeholder, or a path read that silently returned truncated data.

Common situations: Pointing AddVBAProject at a .xlsm/.xlsx file instead of the extracted vbaProject.bin; a download or checkout that corrupted the binary (CRLF conversion, LFS not pulled); reading a missing file into an empty/short slice and passing it on.

Related errors

AI-assisted analysis of qax-os/excelize@f2483381fb (2026-09-02). Data as JSON: /api/errors/5d432f75a2118ebd. Report an issue: GitHub.

Appendix: source

Thrown at errors.go:23

// Package excelize providing a set of functions that allow you to write to and
// read from XLAM / XLSM / XLSX / XLTM / XLTX files. Supports reading and
// writing spreadsheet documents generated by Microsoft Excel™ 2007 and later.
// Supports complex components by high compatibility, and provided streaming
// API for generating or reading data from a worksheet with huge amounts of
// data. This library needs Go version 1.25.0 or later.

package excelize

import (
	"errors"
	"fmt"
	"strings"
)

var (
	// ErrAddVBAProject defined the error message on add the VBA project in
	// the workbook.
	ErrAddVBAProject = errors.New("unsupported VBA project")
	// ErrAttrValBool defined the error message on marshal and unmarshal
	// boolean type XML attribute.
	ErrAttrValBool = errors.New("unexpected child of attrValBool")
	// ErrCellCharsLength defined the error message for receiving a cell
	// characters length that exceeds the limit.
	ErrCellCharsLength = fmt.Errorf("cell value must be 0-%d characters", TotalCellChars)
	// ErrCellStyles defined the error message on cell styles exceeds the limit.
	ErrCellStyles = fmt.Errorf("the cell styles exceeds the %d limit", MaxCellStyles)
	// ErrChartTitle defined the error message on both formula and rich text for
	// chart title.
	ErrChartTitle = errors.New("cannot set both 'Formula' and 'Paragraph' for chart title")
	// ErrColumnNumber defined the error message on receive an invalid column
	// number.
	ErrColumnNumber = fmt.Errorf("the column number must be greater than or equal to %d and less than or equal to %d", MinColumns, MaxColumns)
	// ErrColumnWidth defined the error message on receive an invalid column
	// width.
	ErrColumnWidth = fmt.Errorf("the width of the column must be less than or equal to %d characters", MaxColumnWidth)
	// ErrCoordinates defined the error message on invalid coordinates tuples

View on GitHub (pinned to f2483381fb)