Packages & Blueprints

Resolve publishing errors, invalid bricks.json files, output reference issues, and other package and blueprint problems

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

---

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.

{
  "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:

jq . bricks.json

1. Verify required fields match the bricks.json reference

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.

---

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:

bricks blueprint get outs <child_package_name>@<version>

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

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

For a complete guide on wiring inputs and outputs, see Inputs and Outputs.

---

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

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

CLI

Search for available packages:

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.

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

---

Publish failed

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

How to fix

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:

bricks blueprint publish

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

1. If the upload fails, check your network connection and retry

Bluebricks app

Publishing is available through the CLI or CI/CD integrations. See Creating Artifacts for setup instructions.

Ensure file encoding is UTF-8. Non-UTF-8 files may cause parsing failures during validation.

---

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

For full Bicep type mapping details, see the Bicep artifact reference.

---

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

CLI

Check whether the package is an artifact or a blueprint:

bricks blueprint search -q <package-name>

If you need to deploy this artifact, wrap it in a blueprint first. See Creating Blueprints for instructions.

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

For background on the difference between artifacts and blueprints, see Packages in the main documentation.

---

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

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

CLI

List available versions to find one that is enabled:

bricks blueprint search -q <package-name>

If the specific version you need is disabled, contact your organization admin to enable it.

Pre-release versions are disabled by default. See the FAQ for how to enable them.

---

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

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

CLI

Secrets must be configured through the Bluebricks app. Check which secrets the blueprint requires:

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

Secrets appear in the output with a Secrets. prefix. Add them in the collection settings, then retry.

For background on secrets, see Secrets in the main documentation.

---

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.

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

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

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

bricks.yaml uses lowercase keywords (secrets, data, inputs). The CLI automatically converts these to the capitalized form during publishing.

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 for architecture details

4. Contact support with the error message and your bricks.json