What causes "could not decode base64 data: %s" in evanw/esbuild?

Validate the base64 payload with a decoder before using it as a data URL import

could not decode base64 data

Error message

could not decode base64 data: %s

What it means

When esbuild resolves a data: URL with the ;base64 flag, it calls Go's base64.StdEncoding.DecodeString on the payload. If the base64 data is malformed (wrong characters, incorrect padding, truncated), the decode fails and this error is returned.

Solutions

Validate the base64 payload with a decoder before using it as a data URL import
Ensure standard base64 encoding with correct padding characters (= or ==)
Switch to percent-encoding instead of base64 if the content is plain text

Example fix

// before
import mod from 'data:text/javascript;base64,ZXhwb3J0IGRlZmF1bHQgMQ'
// after (fix padding)
import mod from 'data:text/javascript;base64,ZXhwb3J0IGRlZmF1bHQgMQ=='

Defensive patterns

Strategy: validation

Validate before calling

function makeDataUrl(mimeType, content) {
  const base64 = Buffer.from(content).toString('base64')
  // Verify round-trip
  if (Buffer.from(base64, 'base64').toString() !== content) {
    throw new Error('base64 encoding round-trip failed')
  }
  return `data:${mimeType};base64,${base64}`
}
const url = makeDataUrl('text/javascript', 'export default 1')
// import mod from url // safe to import now

Prevention

Generate data URLs programmatically using Buffer/TextEncoder instead of hand-typing base64
Avoid copying base64 strings from untrusted sources without validation
Prefer percent-encoding over base64 for short text payloads

When it happens

Trigger: Importing a data: URL like 'data:text/javascript;base64,...' where the base64 portion contains invalid characters or incorrect padding.

Common situations: Hand-constructed data URLs with truncated base64, copy-paste errors introducing whitespace or non-base64 characters, or incorrect padding (missing '=' characters).

Related errors

AI-assisted analysis of evanw/esbuild@f6058f8364 (2026-08-09). Data as JSON: /api/errors/07da6443429f40ca. Report an issue: GitHub.

Appendix: source

Thrown at internal/resolver/dataurl.go:65

	// Hard-code a few supported types
	switch mimeType {
	case "text/css":
		return MIMETypeTextCSS
	case "text/javascript":
		return MIMETypeTextJavaScript
	case "application/json":
		return MIMETypeApplicationJSON
	default:
		return MIMETypeUnsupported
	}
}

func (parsed DataURL) DecodeData() (string, error) {
	// Try to read base64 data
	if parsed.isBase64 {
		bytes, err := base64.StdEncoding.DecodeString(parsed.data)
		if err != nil {
			return "", fmt.Errorf("could not decode base64 data: %s", err.Error())
		}
		return string(bytes), nil
	}

	// Try to read percent-escaped data
	content, err := url.PathUnescape(parsed.data)
	if err != nil {
		return "", fmt.Errorf("could not decode percent-escaped data: %s", err.Error())
	}
	return content, nil
}

View on GitHub (pinned to f6058f8364)