helm/helm · error

chart file %q is larger than the maximum file size %d

Error message

chart file %q is larger than the maximum file size %d

What it means

Returned by loader.LoadDir's walker when a file inside the chart directory exceeds archive.MaxDecompressedFileSize (pkg/chart/loader/archive; default 5 MiB, an int64 package variable). This mirrors the decompression-bomb guard used when loading archives and stops the loader from buffering oversized files into memory. The message includes the file name and the enforced limit.

Source

Thrown at pkg/chart/v2/loader/directory.go:104

				return filepath.SkipDir
			}
			return nil
		}

		// If a .helmignore file matches, skip this file.
		if rules.Ignore(n, fi) {
			return nil
		}

		// Irregular files include devices, sockets, and other uses of files that
		// are not regular files. In Go they have a file mode type bit set.
		// See https://golang.org/pkg/os/#FileMode for examples.
		if !fi.Mode().IsRegular() {
			return fmt.Errorf("cannot load irregular file %s as it has file mode type bits set", name)
		}

		if fi.Size() > archive.MaxDecompressedFileSize {
			return fmt.Errorf("chart file %q is larger than the maximum file size %d", fi.Name(), archive.MaxDecompressedFileSize)
		}

		data, err := os.ReadFile(name)
		if err != nil {
			return fmt.Errorf("error reading %s: %w", n, err)
		}

		data = bytes.TrimPrefix(data, utf8bom)

		files = append(files, &archive.BufferedFile{Name: n, ModTime: fi.ModTime(), Data: data})
		return nil
	}
	if err := sympath.Walk(topdir, walk); err != nil {
		return c, err
	}

	return LoadFiles(files)
}

View on GitHub (pinned to 2a29f1770b)

Solutions

1. Identify the oversized file named in the error and shrink or split it below the limit (compress, trim data, or move hosting to an object store/ConfigMap-free delivery).
2. If the large file is legitimately part of the chart, raise the guard in your program before loading: `archive.MaxDecompressedFileSize = 50 * 1024 * 1024` (it exists to protect memory, so size it consciously).
3. Check for accidentally committed build artifacts or test fixtures and remove them from the chart directory.
4. Re-run the load after the change.

Example fix

// before
import "helm.sh/helm/v4/pkg/chart/v2/loader"
c, err := loader.LoadDir("./mychart") // 12 MiB bundled dataset -> error

// after
import "helm.sh/helm/v4/pkg/chart/loader/archive"
archive.MaxDecompressedFileSize = 20 * 1024 * 1024 // raise guard deliberately
c, err := loader.LoadDir("./mychart")

// pre-walk: verify every file is under the limit you will load with
func sizesOK(root string, limit int64) error {
    return filepath.WalkDir(root, func(p string, d fs.DirEntry, err error) error {
        if err != nil { return err }
        if d.IsDir() { return nil }
        fi, err := d.Info()
        if err != nil { return err }
        if fi.Size() > limit { return fmt.Errorf("%s is %d bytes (> %d)", p, fi.Size(), limit) }
        return nil
    })
}

func isFileSizeErr(err error) bool {
    return err != nil && strings.Contains(err.Error(), "larger than the maximum file size")
}

c, err := loader.LoadDir(dir)
if err != nil && strings.Contains(err.Error(), "larger than the maximum file size") {
    // either shrink/split the named file, or consciously raise archive.MaxDecompressedFileSize and retry
}

When it happens

Trigger: Calling loader.LoadDir on a chart containing any single file > 5 MiB by default — large images, binaries, CSV/JSON datasets, or model files placed in the chart; also triggered when the limit variable was lowered programmatically.

Common situations: Charts that bundle static assets (fonts, GeoIP databases, ML models); generated CRD or data files exceeding 5 MiB; forgetting that 'files are small in dev, huge in prod data' after pointing the chart at a big dataset.

Related errors

• unsupported chart version
• cannot load a directory
• unable to load chart archive
• unable to detect chart version, no Chart.yaml found
• cannot load a directory

AI-assisted analysis of helm/helm@2a29f1770b (2026-08-15). Data as JSON: /api/errors/fff0465b1bb239c3. Report an issue: GitHub.