Skip to content

Troubleshooting

Symptom first. Every allez error names the file and the key it objects to, so most rows here are the why behind a message you already have. The example pipelines have their own troubleshooting page.

Loading

You see Cause Do
Unknown environment 'x'. … declares: … --env is not in the root allez.yml environments:. Declare it, or use a declared name.
overrides undeclared environment(s) / names undeclared environment(s) An Override Map key (default plus one key per environment) or an environments: filter (roles, tags, dag nodes, hook steps) has a typo. Fix the spelling.
unknown key(s) at … Allowed: … A misspelt key in allez.yml or a hooks file, or a key at the wrong scope. git belongs under branch-workspace in the root file; environments and dag belong in the root file only. Use a listed key.
no dag: declared The root allez.yml has no dag. Add one node per config file (the dag).
not in the dag, ignored: … A config.yml, overlay or hooks file that no dag node names. Not an error. Fine if you set the file aside on purpose. If it should run, name it in the dag.
`pre_deploy_hooks` entry '…' must be '<sub-folder>/.deploy/hooks/<purpose>.hooks.yml' (or post_deploy_hooks) A dag node names a hooks file outside the sub-folder's .deploy/hooks/ folder. Move the file.
`dag` config '…' is neither '<sub-folder>/config.yml' nor '<sub-folder>/.deploy/config-overlay/<name>.config.yml' A dag node names a config at another place, such as an overlay file outside .deploy/. Move the file under .deploy/config-overlay/.
uses hook 'x', which is in neither …/.allez/hooks nor the allez library The step's action is neither a library hook nor a file in .allez/hooks/ beside fabric/. A hook anywhere else is not read. Where allez finds a hook.
has unknown key(s): … run accepts: … / is missing 'item' The step's keys do not match the hook's run signature. Match the hook's run keys (hooks).
`request` must be a mapping A step key the hook's run takes as a mapping holds a string or a list. Nest the keys under the step.
core.workspace belongs in the sub-folder's config.yml, not in an overlay An overlay tries to change which workspace the folder publishes to. An overlay can only narrow what a deploy publishes; only config.yml says which workspace a folder publishes to.
`branch-workspace.git.connection-name` is required The branch-workspace.git block names no connection. Make the connection once with fab mkdir (git connection) and name it. allez carries no credential.
`branch-workspace.git.base-env` must name one declared environment base-env is misspelt, or names an environment missing from the root environments:. Name the environment whose workspace is git-connected, dev (git).
branch 'main' is protected — provision is for feature branches only (or apply, --branch-workspace) A protected branch (protected-branches); the Run dialog defaults to main. Check out or pick a feature/* branch.
maps 'dev' to the workspace '…' — a long-lived environment allez provision --env dev (or test, prod). Provision creates branch workspaces only. Named environments are made outside allez; use --env feature.

Branch workspaces

You see Cause Do
The pipeline ran but you cannot see your workspace The service principal created it; your access comes only from allez.yml roles. Add your principal by its Entra object id (roles) and re-queue the pipeline; roles are re-applied.
git push rejected after the provision pipeline ran allez deploy --env feature --branch-workspace --commit-to-git committed [skip ci] allez: bind branch workspace after deploy to your branch (what a run does). git pull first. That commit changes many ids; this is expected.
no workspace named '…' exists yet. Run allez provision --env feature deploy --branch-workspace before the branch was provisioned, or the workspace was deleted. Run the provision pipeline on the branch, or allez provision fabric --env feature by hand.
--plan shows an id for a workspace that no longer exists --plan reads the .allez/cache/ cache, which is out of date (conventions). Delete .allez/cache/, or run the verb without --plan once.
! …: git integration failed, continuing — … The workspace was published, but connecting it to the branch or committing it back did not happen. A warning; the run stays green. Find the reason after the dash in the rows below, fix it, then re-queue to bind.
connected to git branch 'feature/x', not 'feature/y' Two branch names produce the same workspace name (both x_y and x-y become the slug x-y). Rename the branch, or disconnect the workspace from git in the portal and re-run.
git initialize for … asks for 'UpdateFromGit' The branch holds an item allez deploy --branch-workspace did not publish: its type is outside item_types_in_scope, or publish.skip.feature skipped the publish. Updating the workspace from git would import it unchanged. Add the type to config.yml item_types_in_scope, or remove the item folder, then re-queue.
… left in the branch: in the branch but not in the workspace Not an error. An item the branch holds and the workspace lacks, such as one publish.exclude_regex excluded, would be deleted by a full commit, so the commit was selective and the item stayed. Nothing, unless the item should have been published: then widen item_types_in_scope or the filter.
fab mkdir fails creating the workspace on the capacity The creating identity is not a Contributor on that capacity. Admin portal → Capacity settings → Contributor permissions: add the service principal (or yourself). Set up.
acl set: [NotFound] '<upn>' identity not found fab acl set -I cannot resolve that UPN. Use the Entra object id for -I; allez.yml roles take object ids too (roles).
git connection '…' does not exist, or this identity cannot see it branch-workspace.git.connection-name names a connection that is absent, or the running identity has no access to it. Make it once with fab mkdir (git connection), or grant the identity use of the existing one.
Workspace … did not finish syncing with git within 600s Fabric's commit-to-git is slow or stuck. Re-queue. A workspace that is already connected goes straight to the commit, or skips it when there is nothing to commit. Check the workspace's source control pane for a conflict.
· …: relation skipped — …config.yml `core.workspace.<env>` must name a workspace that exists The base-env environment's workspace is not named in that sub-folder's config.yml, or does not exist. Name it there, or create it (outside allez).
· …: relation not created — … WorkspaceRelationRootDirectoryMismatch (or InsufficientPrivileges) The base workspace is not connected to git at the same repo root (dev is connected to another directory, or not at all), or the deploying identity is not Contributor on it. The deploy itself succeeded. If dev is connected to main, connect it to its sub-folder's directory (git connection); grant the service principal Contributor on dev.

Deploying

You see Cause Do
'X.Type' was not found in the 'data' workspace. Deploy that workspace first A $allez.<sub-folder>.$items… token names an item an earlier node has not published, or the name is wrong. Check dag order (--plan draws it) and the item's display name.
workspace '…' does not exist for --env x / no workspace named '…' exists for --env x A config.yml names a workspace nobody made. Named environments are made outside allez: create it under exactly that display name, with the service principal as Contributor.
does not have an assigned capacity (fabric-cicd) The target workspace is not on a capacity. Assign one by hand; allez applies capacity only when it creates a branch workspace.
A notebook's schedule did not change after a deploy fabric-cicd may not update a .schedules file when the item already exists (#560, #981); schedules. Check the item's schedule in the workspace; until fabric-cicd fixes it, set it by hand once or with a fab_api step.
fab deploy fails creating an item with 500 InternalServerError after a .schedules rewrite The rule changed enabled alone, leaving "enabled": false beside "enabledControlType": "UserEnabled", a shape Fabric rejects. Capture both keys and write one of Fabric's two shapes (schedules).
403 from a semantic model binding or datasource write The deploying service principal does not own the model. Run a takeover before the publish, as the sample (the solution in fabric/) does in takeover.hooks.yml.
refresh of SemanticModel failed: … cannot access the source Delta table The DirectLake model's tables do not exist in the data workspace: the warehouse has no schema. Check the publish_sqlproj step on the data node ran green before the reporting node (publish_sqlproj).
A publish_sqlproj step fails with a build error naming SQL71561: … has an unresolved reference to object [<warehouse>].[<schema>].[…] A view or procedure refers to an object in this same warehouse by a three-part name (warehouse, schema, object), which the project build treats as an external reference. dbt generates exactly this. Use two-part names (schema, object) for the warehouse's own objects. Keep a dbt-owned schema's views out of the item folder: dbt rebuilds them on every run. A <Build Remove> in the project file is lost the next time Fabric commits the item back to git.
A publish_sqlproj step fails with DataLoss: The column [dbo].[<table>].[<column>] is being dropped, data loss might occur The project drops or narrows a column in a table that holds rows. Fabric refuses the whole publish and leaves the table as it was; the post-deployment script does not run, but the pre-deployment script already has. Make the change forward-only: keep the column, or move its data first in a pre-deployment script that is safe to run again. Check what the pre-deployment script did, since it is not rolled back (publish_sqlproj).
A deploy is green but an item still points at another environment's workspace No parameter.yml rule matched: a literal find_value no longer matches the committed text, or the value is in a file no rule covers. Anchor find_value on the surrounding structure with an is_regex rule and run allez audit, which names every id no rule rewrites.
A publish fails on an item that references a connection (data pipeline, Dataflow, dbt) with a permission or not-found error The connection id is inside the definition, but the connection does not exist for that environment or is not shared with the deploying service principal. Until it is shared, only its owner can see it. Create it as the service principal, or grant it User under Manage connections and gateways, then parameterize the id per environment (external connections).
A dbt job run fails with The datasource type LinkedService is invalid dbt-content.json uses the profile shape from the documentation (connectionSettings.type + properties), not the shape git integration writes (connectionSettings.name + properties.type + typeProperties). Author the job in the Fabric UI once and commit it; keep that shape.