Skip to main content

Documentation Index

Fetch the complete documentation index at: https://buildcharts.dev/llms.txt

Use this file to discover all available pages before exploring further.

This page covers common issues you may encounter when running buildcharts.

​
buildcharts init says the project type is unknown

init currently supports .NET repositories only and expects a .sln or .slnx file. Check:
  • You are running the command from the repository root
  • The repository contains a solution file

​
buildcharts generate cannot find charts/buildcharts/Chart.yaml

BuildCharts expects to run from the repository root. Fix:
  • Run the command from the repo root
  • Or scaffold the repo first with buildcharts init

​
buildcharts generate says the lock file is out of sync

This happens when charts/buildcharts/Chart.lock no longer matches charts/buildcharts/Chart.yaml or the current registry digests. Fix: 
buildcharts update
To skip lock validation for one run: 
buildcharts generate --ignore-lock

​
buildcharts generate says there is no build target

Every build.yml must contain exactly one target with type: build. Check:
  • You have one and only one build target
  • The target type is spelled correctly

​
buildcharts generate says a target type is unknown

Each target type in build.yml must match an alias in charts/buildcharts/Chart.yaml. Example 
dependencies:
  - name: dotnet-test
    alias: test
    version: 0.0.1
    repository: oci://registry-1.docker.io/buildcharts
If build.yml uses type: test, the alias must exist in Chart.yaml.

​
buildcharts generate says build.yml is invalid

This usually means the YAML shape does not match what BuildCharts expects for variables or target definitions. Common causes:
  • A variable scalar contains =
  • A variable name is empty
  • A variable mapping contains more than one entry
  • A variable mapping is missing default
  • A target mapping is missing type
  • type is not a string or list of strings
Fix:
  • Validate the structure against the Metadata page
  • Keep variables as either a mapping or a sequence of scalars/mappings
  • Make sure every target definition includes a valid type

​
buildcharts generate shows a warning for an unknown plugin

If a plugin name is not registered, BuildCharts does not fail generation. It skips that plugin and prints a warning instead. Check:
  • The plugin name is spelled exactly right
  • The version suffix is included, for example NuGetAuthenticate@v1
  • The plugin exists in the built-in plugin list
If you expected the plugin to modify the generated HCL or write files under .buildcharts, verify those outputs explicitly after generation.

​
buildcharts summary cannot find Docker build history

buildcharts summary uses the latest Docker Buildx history. It only works after you have run a Bake build. Fix:
  • Run buildcharts generate
  • Run docker buildx bake --file .buildcharts/docker-bake.hcl
  • Run buildcharts summary again

​
--use-inline-dockerfiles fails with a missing Dockerfile

When you use buildcharts generate --use-inline-dockerfiles, BuildCharts expects the pulled chart Dockerfiles to exist under .buildcharts/<chart-name>/Dockerfile. Fix:
  • Rerun buildcharts generate
  • Verify chart pull succeeded
  • Verify the referenced chart alias exists in Chart.yaml

​
Registry authentication failures

pull, update, and generate use Docker credentials from:
  • <DOCKER_CONFIG>/config.json
  • ~/.docker/config.json
Private OCI registries require Docker authentication before running BuildCharts.
Last modified on April 19, 2026