Fjall Docs — Deploy Production-Ready AWS Infrastructure in Minutes

Three versions, one deploy

Every Fjall deploy involves three independently versioned pieces:

Piece	Where it comes from	Example
The deploy engine (`fjall` CLI)	Installed globally (`npm install -g fjall`) or by your CI pipeline	`fjall 6.x`
The infrastructure constructs	`@fjall/components-infrastructure`, pinned in your application’s `package.json`	`^6.0.0`
The AWS CDK CLI	Bundled inside the deploy engine — you never install it yourself	`2.x`

Your application pins its constructs version, but the CLI that runs the deploy is chosen separately — on your machine or in CI. If the engine is older than the constructs that synthesised your infrastructure, the deploy can go wrong silently: services dropped from the build set, images built without the options your runtime needs, or permissions that no longer line up. Fjall closes this gap with an engine-compatibility check. At synthesis, your constructs stamp the minimum engine version they require into the deployment artefact. Before building, pushing, or touching CloudFormation, the engine reads that constraint and refuses loudly if it cannot honour it — for application deploys and organisation-level deploys and destroys alike. A refusal always happens before anything in AWS is changed.

Newer engines deploying older applications are always supported. Upgrading fjall never locks you out of redeploying an app synthesised by an earlier version. The check only bites in the unsafe direction: an old engine driving newer infrastructure code.

The refusal messages and their cures

Message starts with…	What it means	Cure
`This assembly … requires deploy engine >= X.0.0`	Your installed `fjall` is older than the constructs your app is pinned to	Upgrade the engine: `npm install -g fjall@X` (in CI, set `cli-version` to `X` or `auto`)
`This assembly … requires the deploy engine's bundled aws-cdk CLI`	The engine’s bundled AWS CDK CLI is older than the constructs were built against	Upgrade the engine — the correct CDK CLI ships inside it
`This assembly declares manifest schema version N`	The deployment artefact uses a newer format than this engine can read	Upgrade the engine
`This assembly carries an engine-compatibility block with no usable…` / `…declares an unparseable minimum engine version`	The constraint in the artefact is corrupted — usually a broken or partially updated `node_modules`	Reinstall your app’s dependencies and re-synthesise (re-run the deploy); if it persists, reinstall `fjall`
`…the running engine version could not be determined`	The `fjall` install itself looks broken	Reinstall the engine: `npm install -g fjall@X`

Applications created before Fjall 4.3 carry no constraint; they deploy exactly as before.

Upgrading from 5.x to 6

When your application moves to @fjall/components-infrastructure 6.x, upgrade the engine everywhere a deploy runs:

# Locally
npm install -g fjall@6
fjall --version   # confirm 6.x

# GitHub Actions / Buildkite plugin inputs
cli-version: "6"     # or "auto" to derive the major from your constructs pin

The same-major rule is all you need to remember: engine major = constructs major. A 6.x engine deploys every 6.x app (and any older app). The same steps apply to any earlier major move (4.x to 5, and so on).

Emergency override

If you have verified an engine/constructs pairing yourself and need to push a deploy through anyway, set:

FJALL_ALLOW_ENGINE_SKEW=1 fjall deploy api

This downgrades the refusal to a warning for that run and is audit-logged. Treat it as an emergency escape hatch, not a workflow: deploying across an engine skew can make silently wrong infrastructure changes — exactly the failure the check exists to stop. There is no CLI flag for this; the environment variable is the only override, and it works identically in local runs and both CI plugins.

Install & Setup

Application Deploy

Organisation Setup

Organisation Deploy

Engine Compatibility

Three versions, one deploy

The refusal messages and their cures

Upgrading from 5.x to 6

Emergency override

Next steps

CI/CD Integration

CLI Installation

​Three versions, one deploy

​The refusal messages and their cures

​Upgrading from 5.x to 6

​Emergency override

​Next steps

CI/CD Integration

CLI Installation

Three versions, one deploy

The refusal messages and their cures

Upgrading from 5.x to 6

Emergency override

Next steps