# Packages & Blueprints

## Quick reference

| Symptom                          | Cause                                                                    | Fix                                                                                             |
| -------------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
| Invalid `bricks.json`            | Missing required fields or bad JSON syntax                               | Validate JSON; ensure `name`, `version`, and `packages` are present                             |
| Blueprint outputs error          | Invalid `Data.<pkg>.<output>` reference                                  | Check case sensitivity; verify the output exists in the child blueprint                         |
| Outputs must reference a package | No output uses `Data.<packageId>.<outputName>`                           | Add at least one output that references a child package                                         |
| Invalid lowercase references     | Used `data.` or `props.` instead of `Data.` or `Props.` in `bricks.json` | Capitalize to `Data.` and `Props.`, or switch to `bricks.yaml` (which uses lowercase by design) |
| Invalid property name            | Name doesn't match allowed pattern                                       | Rename to start with a letter or underscore                                                     |
| Package not found                | Package disabled, restricted, or misspelled                              | Use `bricks blueprint search -q <term>` to find packages                                        |
| Publish failed                   | Missing IaC files or upload error                                        | Verify all required files are present; retry                                                    |

***

## Invalid `bricks.json`

The `bricks.json` file defines your artifact or blueprint metadata. Publishing fails if the file is malformed or missing required fields.

### Required fields

```jsonc
{
  "name": "my_package",       // Letters, numbers, underscores only
  "version": "1.0.0",         // Semantic versioning (MAJOR.MINOR.PATCH)
  "packages": []              // Required for blueprints
}
```

### Common mistakes

* **Invalid JSON syntax**: trailing commas, missing quotes, or unescaped characters
* **Missing `version`**: every package needs a semantic version
* **Invalid name**: package names must use underscores, not hyphens (`aws_vpc`, not `aws-vpc`)

### How to fix

1. Validate your JSON with a linter or `jq`:

```bash
jq . bricks.json
```

2. Verify required fields match the [bricks.json reference](https://docs.bluebricks.co/bluebricks-documentation/core-concepts/packages/overview/bricks.json)

{% hint style="info" %}
You can also use `bricks.yaml` format, which has the same fields but uses YAML syntax. If both files exist, `bricks.yaml` takes priority.
{% endhint %}

***

## Blueprint output reference errors

Blueprint outputs use the `Data.<packageId>.<outputKey>` syntax to wire values between packages. Bluebricks validates these references at publish time and rejects blueprints with invalid output wiring.

### Common causes

* **Case mismatch**: in `bricks.json`, `Data` and `Props` must be capitalized (`Data.my_pkg.endpoint`, not `data.my_pkg.endpoint`). In `bricks.yaml`, use lowercase (`data.my_pkg.endpoint`, `inputs.region`, `secrets.db_password`)
* **Wrong package ID**: the package ID in the reference doesn't match a package in the blueprint
* **Output doesn't exist in child blueprint**: the child blueprint does not define the output you referenced. The error message lists the invalid references and the outputs that are available in each child
* **No output references at all**: at least one blueprint output must reference a package using `Data.<packageId>.<outputName>`

### Error messages

| Error                                                                        | Meaning                                                                                                          |
| ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `Blueprint validation failed... The following output references are invalid` | One or more `Data.<packageId>.<outputName>` references point to outputs that do not exist in the child blueprint |
| `Blueprint outputs must reference at least one package`                      | None of your blueprint outputs use a `Data.<packageId>.<outputName>` reference                                   |
| `Blueprint contains invalid lowercase references`                            | You used `data.` or `props.` in `bricks.json` instead of `Data.` or `Props.`                                     |

### How to fix

1. Open your `bricks.json` or `bricks.yaml`
2. Verify each output reference matches the exact package ID and output key
3. Check the child package outputs to confirm the referenced key exists:

```bash
bricks blueprint get outs <child_package_name>@<version>
```

```jsonc
// Correct syntax
"value": "Data.database.connection_string"

// Wrong: lowercase "data" (bricks.json only)
"value": "data.database.connection_string"
```

{% hint style="info" %}
For a complete guide on wiring inputs and outputs, see [Inputs and Outputs](https://docs.bluebricks.co/bluebricks-documentation/core-concepts/packages/inputs-and-outputs).
{% endhint %}

***

## Invalid property or output names

Property and output names must match the pattern `^[a-zA-Z_][a-zA-Z0-9_]*$`. Names that start with a number or contain special characters are rejected.

### How to fix

* Start names with a letter or underscore
* Use only letters, numbers, and underscores
* Replace hyphens with underscores

```jsonc
// Valid
"my_property": "value"
"_internal_prop": "value"

// Invalid
"123-prop": "value"
"my-property": "value"
```

***

## Package not found

The `PACKAGE_NOT_FOUND` error occurs when a blueprint references a package that cannot be resolved.

### Common causes

* **Misspelled package name**: check for typos in the package reference
* **Package not published**: the package hasn't been published to your organization
* **Version not enabled**: pre-release versions may be disabled by your admin
* **Policy restriction**: the Allowed Blueprints policy may block specific packages

### How to fix

{% tabs %}
{% tab title="CLI" %}
Search for available packages:

```bash
bricks blueprint search -q <search-term>
```

If the package exists but you can't access it, contact your organization admin to check version availability and policies.
{% endtab %}

{% tab title="Bluebricks app" %}

1. Go to the **Packages** page
2. Search for the package by name
3. Verify the version you need is published and enabled
4. Check collection policies under the collection's **Policies** tab under **Allowed Blueprints**
   {% endtab %}
   {% endtabs %}

***

## Publish failed

Blueprint or artifact publishing can fail due to missing files, unsupported file types, or upload errors.

### How to fix

{% tabs %}
{% tab title="CLI" %}

1. Verify your `bricks.json` is valid (see above)
2. Ensure all required IaC files are present in the source directory:
   * **Terraform/OpenTofu**: at least one `.tf` file
   * **Helm**: a valid `Chart.yaml`
   * **CloudFormation**: a template file (`.yaml` or `.json`)
   * **Bicep**: a `.bicep` file
3. Publish from the directory containing your `bricks.json`:

```bash
bricks blueprint publish --src .
```

4. If the upload fails, check your network connection and retry
   {% endtab %}

{% tab title="Bluebricks app" %}
Publishing is available through the CLI or CI/CD integrations. See [Creating Artifacts](https://docs.bluebricks.co/bluebricks-documentation/core-concepts/packages/artifacts-overview/creating-artifacts) for setup instructions.
{% endtab %}
{% endtabs %}

{% hint style="warning" %}
Ensure file encoding is UTF-8. Non-UTF-8 files may cause parsing failures during validation.
{% endhint %}

***

## Still stuck?

1. Enable logging: `bricks logger enable`
2. Run the failing command again and check `~/.bricks/bricks-cli.log`
3. Review the [Blueprints Overview](https://docs.bluebricks.co/bluebricks-documentation/core-concepts/packages/blueprints-overview) for architecture details
4. [Contact support](https://www.bluebricks.co/support) with the error message and your `bricks.json`