> ## Documentation Index
> Fetch the complete documentation index at: https://buildcharts.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={"theme":{"light":"plastic","dark":"plastic"}}
buildcharts update
```

To skip lock validation for one run:

```bash theme={"theme":{"light":"plastic","dark":"plastic"}}
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**

```yaml theme={"theme":{"light":"plastic","dark":"plastic"}}
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](/core-features/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.