Common issues

Diagnose the most common BuildCharts setup, validation, and generation failures.

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

If you intentionally want 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

If your OCI registry is private, authenticate with Docker before running BuildCharts.