> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fjall.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Engine Compatibility
> How Fjall checks that the CLI deploying your application is compatible with the infrastructure code that synthesised it, what each refusal message means, and how to upgrade.
## 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:
```bash theme={null}
# 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:
```bash theme={null}
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.
## Next steps
Pin or auto-derive the engine version in your pipelines
Install or upgrade the fjall CLI