Troubleshooting

Use this page when a lab step fails and the local hint is not enough. Start with the area that matches the symptom, then go back to the linked lab step.

Install and PATH

pwsh, git, python, node, code, or gh is not found

Cause: the tool is not installed, or the terminal was opened before the installer updated PATH.

Fix: close every terminal, open PowerShell 7, and rerun the prerequisite check:

pwsh ./scripts/Test-Prerequisites.ps1

Fix the first required failure. On Windows, install from Lab 00 step 2. Then rerun Lab 01 step 5.

Windows says the path is too long during clone or validation

Cause: Git for Windows long paths are not enabled, or the repo is cloned under a deep folder.

Fix: run:

git config --global core.longpaths true

If the repo path is still long, clone again to a short path such as C:\src\contoso-pharmacy-lab. See Lab 00 step 3 and Lab 01 step 2.

PowerShell execution policy

PowerShell blocks a script with an execution policy error

Cause: Windows PowerShell policy blocks local scripts. The labs use PowerShell 7, but Windows policy can still block downloaded files.

Fix: in PowerShell 7, run:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

If your organization blocks policy changes, run a single script with:

pwsh -ExecutionPolicy Bypass -File ./scripts/Initialize-DevEnvironment.ps1

Return to Lab 01 step 4.

Python and `.venv`

python opens the Microsoft Store

Cause: Windows App Execution Alias is taking python before the real Python install.

Fix: install Python 3.12 or later from the official installer, then reopen PowerShell. If needed, turn off the Store alias in Settings > Apps > Advanced app settings > App execution aliases. Rerun Lab 00 step 4.

Initialize-DevEnvironment.ps1 fails while installing packages

Cause: Python is too old, the virtual environment is half-created, or a proxy blocks package downloads.

Fix: check Python first:

python --version

Then recreate the environment:

pwsh ./scripts/Initialize-DevEnvironment.ps1 -Force

If a corporate proxy blocks downloads, ask IT to allow PyPI and npm registry access for development tools. Return to Lab 01 step 4.

Git and long paths

Restore-LabCheckpoint.ps1 says the upstream remote is missing

Cause: the checkpoint restore script fetches tags from the upstream lab repo, and your clone does not have the upstream remote.

Fix: add the remote:

git remote add upstream https://github.com/sabajamalian/fabric-powerbi-ai-devops-demo.git
git fetch upstream --tags

Then rerun the restore command from Lab 01 step 3.

Git status shows unexpected Power BI files

Cause: Power BI Desktop wrote local cache or settings files, or the ignore rules were changed.

Fix: do not commit .pbi/localSettings.json, .pbi/cache.abf, or *.pbix. Restore the ignore rules from Git if needed and rerun Lab 02 step 5.

VS Code and Copilot Chat

Agent mode, tools, or the agent picker is missing

Cause: VS Code is old, Copilot Chat is not signed in, or org policy disables the feature.

Fix: update VS Code, sign in with GitHub, open View > Chat, and verify the agent picker. If this is a managed account, ask your admin to enable Copilot Chat, agent mode, custom agents, and MCP. Start at Lab 00 step 6.

References do not include repo instructions or path instructions

Cause: VS Code did not load the workspace as trusted, the file does not match the applyTo glob, or the customization file has invalid frontmatter.

Fix: trust the workspace, open the repo root, and check the file under .github/instructions/. Then retry Lab 03 step 3.

Custom agents not appearing

A custom agent file exists but the agent is not in the picker

Cause: VS Code loaded a subfolder instead of the repo root, or the .agent.md frontmatter is invalid.

Fix: open the repo root. Run Chat: Open Customizations from the Command Palette (Ctrl+Shift+P, macOS: Cmd+Shift+P) and check the Agents tab. If needed, run Developer: Reload Window. For Lab 14, validate with:

pwsh ./scripts/Invoke-Validation.ps1 -Only customizations

Return to Lab 14 step 3.

Skills not loading

A skill folder exists but Copilot ignores it

Cause: SKILL.md frontmatter is missing, the name does not match the folder, or the description is too vague for the model to choose it.

Fix: ensure name is lowercase hyphenated text and matches the folder exactly. Add a description that states what the skill does and when to use it. Rerun Lab 14 step 5.

The Skills for Fabric skill is not installed

Cause: APM did not run or could not write .agents/skills/semantic-model-authoring/.

Fix: run APM from the repo root:

apm install --only apm --target copilot

Then continue with Lab 06 step 2.

MCP server issues

Power BI Modeling MCP server will not start

Cause: Node.js is missing, the extension is old, MCP policy is disabled, or Power BI Desktop is not open.

Fix: rerun prerequisites, update VS Code extensions, open fabric\ContosoPharmacy.pbip in Desktop, then use Command Palette > MCP: List Servers. Return to Lab 04 step 2.

Tool calls are skipped or the agent says tools are unavailable

Cause: the tools are unchecked in the tools picker, or the active agent does not include the MCP tool namespace.

Fix: in Chat, open the tools picker and select the Power BI Modeling tools. Use the intended custom agent, such as question-tester or model-improver. See MCP.

Power BI Desktop and PBIP

Desktop cannot find C:\ContosoPharmacyDemo\data

Cause: the Windows data junction was not created or was removed.

Fix: close Desktop, then run:

pwsh ./scripts/Set-LocalDataLink.ps1

Reopen the PBIP and refresh. See Lab 02 step 1.

Desktop rewrites files after an agent edits TMDL

Cause: Desktop had the model open in memory and saved over the file edits.

Fix: close Desktop before text edits. Restore the affected files with Git, rerun the agent task, and reopen Desktop only after validation. See Lab 07 step 7.

Report bindings

Report visuals show missing fields after renames

Cause: PBIR visuals still point at old table or column names.

Fix: run:

pwsh ./scripts/Test-ReportBindings.ps1

Ask model-improver to fix the listed files using the pbir-rebinding skill. Return to Lab 07 step 6.

Hooks

The hook does not deny edits to protected files

Cause: hooks are disabled, .venv was not initialized, or the active surface does not support the hook file.

Fix: run initialization, then inspect .github/hooks/guardrails.json and out/hooks/session.log. The hook entry points are:

    "preToolUse": [
      {
        "type": "command",
        "bash": "./scripts/hooks/run-hook.sh pre-tool-use",
        "powershell": "pwsh -NoProfile -File ./scripts/hooks/run-hook.ps1 -HookEvent pre-tool-use",
        "cwd": ".",
        "timeoutSec": 20
      }
    ],
    "postToolUse": [
      {
        "type": "command",
        "bash": "./scripts/hooks/run-hook.sh post-tool-use",
        "powershell": "pwsh -NoProfile -File ./scripts/hooks/run-hook.ps1 -HookEvent post-tool-use",
        "cwd": ".",
        "timeoutSec": 30
      }

View .github/hooks/guardrails.json on GitHub

Return to Lab 11 step 4.

The post-edit TMDL lint is noisy

Cause: the hook runs lint after TMDL edits. It is supposed to surface syntax problems early.

Fix: fix the first lint error, then rerun:

pwsh ./scripts/Invoke-Validation.ps1 -Only tmdl

Return to Lab 11 step 5.

Copilot CLI

copilot is not found or not signed in

Cause: Copilot CLI is optional in setup, but required for Lab 11.

Fix: install it from the current official instructions, reopen the terminal, and run copilot once to sign in. Then retry Lab 11 step 1.

Copilot CLI does not load repo customizations

Cause: the CLI session did not start from the repo root, or customizations are invalid.

Fix: start the CLI from the repo root and run customization validation:

pwsh ./scripts/Invoke-Validation.ps1 -Only customizations

CI failures

The validate job fails on Linux or Windows

Cause: CI runs the same tenant-free validation as local setup. A TMDL lint error, binding break, expected-answer drift, customization error, or hygiene issue can fail it.

Fix: run the same validation locally:

pwsh ./scripts/Invoke-Validation.ps1

Fix the first failure. See CI workflows and Lab 12 step 5.

Dependency review fails on a pull request

Cause: the PR changed a dependency manifest and GitHub dependency review found a moderate or higher issue.

Fix: update or remove the dependency change. If you did not mean to change dependencies, restore the manifest and lockfile.

Cloud agent

Copilot cannot be assigned to an issue

Cause: Copilot cloud agent is not enabled for the repo, your plan does not include it, or org policy blocks it. Needs a paid Copilot plan

Fix: check repository settings and ask your org admin to enable cloud agent. Then retry Lab 13 step 3.

Cloud agent setup steps fail

Cause: .github/workflows/copilot-setup-steps.yml failed before the agent started. Common causes are blocked package downloads or a workflow edit that changed the required job name.

Fix: open the session log, expand setup, and compare the workflow with the repo file:

jobs:
  copilot-setup-steps:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: "3.12"

      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
        with:
          node-version: "22"

      - name: Python tools and validation
        shell: pwsh
        run: ./scripts/Initialize-DevEnvironment.ps1

      # Installs the pinned Skills for Fabric skill from apm.yml into .agents/skills, where the
      # cloud agent discovers project skills. --only apm skips the MCP servers that package declares.
      - name: Skills for Fabric (APM)
        run: |
          python -m venv "$RUNNER_TEMP/apm"
          "$RUNNER_TEMP/apm/bin/pip" install --disable-pip-version-check --quiet apm-cli==0.31.0
          "$RUNNER_TEMP/apm/bin/apm" install --only apm --target copilot

View .github/workflows/copilot-setup-steps.yml on GitHub

Return to Lab 13 step 4.

Cloud agent tries to use Power BI Desktop

Cause: the task is not scoped for Linux.

Fix: comment on the PR with @copilot and tell it to edit TMDL and AI-prep files as text, then run pwsh ./scripts/Invoke-Validation.ps1. See Lab 13 step 5.

Lab site locally

The lab site will not start

Cause: Node.js is missing, site dependencies are not installed, or a previous dev server owns the port.

Fix: run the site helper from the repo root:

pwsh ./scripts/lab/Start-LabSite.ps1

If you only need a static check, use:

pwsh ./scripts/lab/Start-LabSite.ps1 -Build

The script is described in Scripts.

Progress checkboxes disappeared

Cause: progress is stored in browser local storage. A different browser, profile, or site URL has different storage.

Fix: use the same browser and URL, or reset progress on /progress/.

Checkpoint restore

Checkpoint restore refuses to run with uncommitted changes

Cause: the script protects your work before it restores fabric/ and lab/samples/ from a tag.

Fix: commit, stash, or discard your changes. Then run:

pwsh ./scripts/lab/Restore-LabCheckpoint.ps1 -Checkpoint lab09-complete

See Lab 01 step 3.

Checkpoint tag is missing

Cause: the upstream tags were not fetched, or the upstream remote points somewhere else.

Fix: run:

git remote -v
git fetch upstream --tags
pwsh ./scripts/lab/Restore-LabCheckpoint.ps1 -List

Troubleshooting

Install and PATH

PowerShell execution policy

Python and .venv

Git and long paths

VS Code and Copilot Chat

Custom agents not appearing

Skills not loading

MCP server issues

Power BI Desktop and PBIP

Report bindings

Hooks

Copilot CLI

CI failures

Cloud agent

Lab site locally

Checkpoint restore

Python and `.venv`