# Packages & Blueprints

## Quick reference

| Symptom                                       | Cause                                                                    | Fix                                                                                             |
| --------------------------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
| Invalid `bricks.json`                         | Missing required fields or bad JSON syntax                               | Validate JSON; ensure `name` and `version` 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                                                    |
| Bicep inputs or outputs missing after publish | Entry file not named `main.bicep`                                        | Rename your Bicep entry file to `main.bicep` and republish                                      |
| Bicep environment creation fails with `400`   | Input value format mismatch (e.g., array passed as a flat string)        | Ensure array values are passed as proper JSON arrays, not stringified values                    |
| Bicep deployment fails with wrong scope       | Template uses `targetScope = 'subscription'`                             | Refactor to resource group scope; Bluebricks only supports resource group deployments           |
| "Artifact cannot be deployed"                 | Attempted to deploy an artifact instead of a blueprint                   | Wrap the artifact in a blueprint; [details below](#artifact-cannot-be-deployed)                 |
| "Package version not enabled" or "disabled"   | Version exists but is disabled for your organization                     | Enable the version in the app, or use an enabled version                                        |
| "Missing required secrets"                    | Secrets not configured in the collection                                 | Add secrets in collection settings; [details below](#missing-required-secrets)                  |

***

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

All packages require `name` and `version`. Blueprints additionally require `packages` and `outs`. Artifacts require `native`.

```jsonc
{
  "name": "my_package",       // Must start with a letter, only letters/numbers/underscores
  "version": "1.0.0",         // Semantic versioning (MAJOR.MINOR.PATCH)
  "packages": [],             // Blueprint-specific (not required for artifacts)
  "outs": {}                  // Blueprint-specific (not required for artifacts)
}
```

### Common causes

* **Invalid JSON syntax**: trailing commas, missing quotes, or unescaped characters
* **Missing `version`**: every package needs a semantic version
* **Invalid name**: package names must start with a letter, end with a letter or number, and use only letters, numbers, and underscores. Hyphens are not allowed (`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/orchestration/packages/overview/bricks.json)

{% hint style="info" %}
You can also use `bricks.yaml` (or `bricks.yml`) format, which uses YAML syntax with slightly different field names (`inputs` instead of `props`, `outputs` instead of `outs`). 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/orchestration/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. This is a separate validation from package names, which have stricter rules (must start with a letter, no leading underscores).

### 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 `main.bicep` file (entry file must use this exact name)
3. Publish from the directory containing your `bricks.json`:

```bash
bricks blueprint publish
```

The CLI uses the current working directory by default. Use `--src <path>` to specify a different directory.

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/orchestration/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 %}

***

## Bicep inputs or outputs missing after publish

Your Bicep artifact publishes successfully but inputs (props) or outputs are empty or only show `location` and `resourceGroup`.

### Common causes

* **Entry file not named `main.bicep`**: Bluebricks requires the Bicep entry file to be named `main.bicep`. If your file uses a different name (e.g., `windows-vm.bicep`, `deploy.bicep`), parameter and output extraction is skipped
* **Regex fallback parser misreads typed arrays**: if the Bicep CLI is unavailable during publishing, the fallback parser cannot map typed array parameters like `int[]` to the correct Bluebricks type. The raw type string is passed through unmapped instead of being recognized as a list. This does not occur on the primary publish path

### How to fix

1. Rename your Bicep entry file to `main.bicep`. Module files referenced by the entry file can use any name
2. Republish the artifact
3. Verify that inputs and outputs appear correctly on the blueprint page in the Bluebricks app

{% hint style="info" %}
For full Bicep type mapping details, see the [Bicep artifact reference](https://docs.bluebricks.co/bluebricks-documentation/orchestration/packages/artifacts-overview/bicep#inputs).
{% endhint %}

***

## Bicep environment creation fails with `400`

Creating an environment returns `Server error (400)` from the `/api/v1/env/create` endpoint.

### Common causes

* **Array value passed as a flat or stringified value**: list-type inputs must be proper JSON arrays (e.g., `["a","b"]`), not comma-separated strings or other scalar formats
* **Missing required inputs**: required properties were not provided during environment creation

### How to fix

1. Open your blueprint in the Bluebricks app and check the expected input types
2. For list-type inputs, ensure the value is a proper JSON array (e.g., `[32, 64]`), not a stringified or flat value
3. Verify that all required inputs have values assigned in the collection or environment configuration

***

## Bicep deployment fails with wrong scope

The deployment fails because the Bicep template targets a scope that Bluebricks does not support.

### Common causes

* **Template uses `targetScope = 'subscription'`**: Bluebricks runs all Bicep deployments at the resource group scope. Subscription, management group, and tenant scopes are not supported

### How to fix

1. Remove or change `targetScope` in your Bicep template so it deploys at the resource group level
2. Move any subscription-level resources (e.g., resource group creation, policy assignments) into a separate process outside Bluebricks
3. Republish the artifact

***

## Artifact cannot be deployed

You see `Artifact '<name>' cannot be deployed. Only blueprints support deployment` when you try to deploy an artifact directly. Artifacts are the building blocks of blueprints, but they are not deployable on their own.

### Why this happens

Artifacts and blueprints are both packages, but they serve different roles:

* An **artifact** wraps a single IaC component (one Terraform module, one Helm chart, etc.)
* A **blueprint** composes one or more packages into a deployable unit with wired inputs, outputs, and relationships

Only blueprints can be installed into environments. If you try to deploy an artifact, Bluebricks rejects the request.

### How to fix

{% tabs %}
{% tab title="CLI" %}
Check whether the package is an artifact or a blueprint:

```bash
bricks blueprint search -q <package-name>
```

If you need to deploy this artifact, wrap it in a blueprint first. See [Creating Blueprints](https://docs.bluebricks.co/bluebricks-documentation/orchestration/packages/blueprints-overview/creating-blueprints) for instructions.
{% endtab %}

{% tab title="Bluebricks app" %}

1. Go to the **Packages** page and find the package
2. Check the package type in the details view (artifact vs. blueprint)
3. If it is an artifact, look for an existing blueprint that includes it, or create a new blueprint
   {% endtab %}
   {% endtabs %}

{% hint style="info" %}
For background on the difference between artifacts and blueprints, see [Packages](https://docs.bluebricks.co/bluebricks-documentation/orchestration/packages) in the main documentation.
{% endhint %}

***

## Package version disabled or not enabled

You see `Package '<name>' version '<version>' is not enabled` or `is disabled` when the package version exists but your organization cannot use it. This is different from "Package not found," where the package does not exist at all.

### How to fix

{% tabs %}
{% tab title="Bluebricks app" %}

1. Go to the **Packages** page and find the package
2. Open the version list and check whether the version you need is enabled
3. If it is disabled, an organization admin can enable it from the package settings
   {% endtab %}

{% tab title="CLI" %}
List available versions to find one that is enabled:

```bash
bricks blueprint search -q <package-name>
```

If the specific version you need is disabled, contact your organization admin to enable it.
{% endtab %}
{% endtabs %}

{% hint style="info" %}
Pre-release versions are disabled by default. See the [FAQ](/docs/help/readme.md) for how to enable them.
{% endhint %}

***

## Missing required secrets

You see `Missing required secrets: <names>` when the blueprint requires secrets that have not been configured in the collection. Secrets are distinct from properties: they are sensitive values stored in the collection's secret manager and referenced in blueprints via `Secrets.<name>`.

### Why this is different from missing properties

* **Properties** are set during environment creation or inherited from the collection. The error `Missing required properties` covers these
* **Secrets** must be configured in the collection settings before deploying. They cannot be passed at deploy time

### How to fix

{% tabs %}
{% tab title="Bluebricks app" %}

1. Go to the collection's **Settings** tab
2. Open the **Secrets** section
3. Add each secret listed in the error message
4. Retry the deployment
   {% endtab %}

{% tab title="CLI" %}
Secrets must be configured through the Bluebricks app. Check which secrets the blueprint requires:

```bash
bricks blueprint get props <blueprint-name>@<version>
```

Secrets appear in the output with a `Secrets.` prefix. Add them in the collection settings, then retry.
{% endtab %}
{% endtabs %}

{% hint style="info" %}
For background on secrets, see [Secrets](https://docs.bluebricks.co/bluebricks-documentation/orchestration/collections/secrets) in the main documentation.
{% endhint %}

***

## Secrets treated as plain strings

Secret references are passed to the IaC runner as literal strings (e.g., `"secrets.adminUsername"`) instead of being resolved to the actual secret value. The run fails because the variable receives the string `"secrets.adminUsername"` rather than the secret's contents.

### Common causes

* **Wrong case in bricks.json**: `bricks.json` requires capitalized keywords (`Secrets.my_key`, `Data.pkg.output`, `Props.region`). Using lowercase causes the reference to be treated as a plain string. Publishing will reject these with a `Blueprint contains invalid lowercase references` error.

```json
// Wrong
"value": "secrets.my_key"

// Correct
"value": "Secrets.my_key"
```

The same rule applies to `Data` and `Props` in `bricks.json`.

* **Quoted value in bricks.yaml**: wrapping the reference in quotes can cause it to be interpreted as a literal string rather than an expression

```yaml
# Wrong: treated as a plain string
props:
  db_password: "secrets.db_password"

# Correct: treated as a secret reference
props:
  db_password: secrets.db_password
```

{% hint style="info" %}
`bricks.yaml` uses lowercase keywords (`secrets`, `data`, `inputs`). The CLI automatically converts these to the capitalized form during publishing.
{% endhint %}

### How to fix

1. **bricks.json**: verify that `Secrets`, `Data`, and `Props` are capitalized
2. **bricks.yaml**: make sure the value is not wrapped in quotes
3. Republish the blueprint and retry the deployment

***

## Need more help?

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://bluebricks.co/docs/help/troubleshooting/packages.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.