Crossplane "crossplane xpkg build" failed in CI

By Daniel Zoghalchali·Latchkey

crossplane xpkg build bundles a package directory (its crossplane.yaml meta file plus CRDs, compositions, or a function image) into an .xpkg. It fails when the meta file is missing or invalid, or a bundled manifest does not parse.

What this error means

A build step running crossplane xpkg build exits non-zero with a message about the package meta file, an invalid manifest, or a missing directory.

crossplane: error: failed to build package: crossplane.yaml: not found in the
package root: open /home/runner/work/pkg/crossplane.yaml: no such file or directory

Common causes

The package meta file is missing or in the wrong place

xpkg build expects a crossplane.yaml in the package root; without it, there is nothing describing the package to build.

A bundled manifest is invalid

A composition, XRD, or CRD in the package directory fails to parse, so the build aborts.

How to fix it

Build from a directory with a valid meta file

1. Ensure crossplane.yaml (Configuration or Function meta) sits in the package root.
2. Point build at that directory and set an output path.
3. Fix any manifest the error names, then rebuild.

crossplane xpkg build \
  --package-root=./package \
  --package-file=configuration.xpkg

Validate the package manifests first

Run validate over the package directory so a bad manifest fails with a clear message before build.

crossplane beta validate ./crds ./package

How to prevent it

• Keep a valid crossplane.yaml in the package root.
• Validate package manifests before building the xpkg.
• Build packages in PR so structural errors surface early.

Frequently asked questions

Related guides

References

• Terraform documentation
• GitHub Actions documentation