Troubleshooting

Use this page to diagnose setup, Azure deployment, validation, and Accelerator agent issues during the MicroHack.

Quick Diagnosis

Tip

Start here. Identify your failure type, then follow the link to the relevant section.

Expand table

Symptom	Go to	Likely category
Can't log in to Azure, subscription not found	Azure CLI	Auth / subscription issue
RequestDisallowedByPolicy error	Policy Errors	Azure Policy denial
QuotaExceeded, region capacity errors	Quota Errors	Insufficient Azure quota
Container won't build, extensions missing	Dev Container	Environment setup issue
bicep build fails, module errors	Bicep	Template/syntax issue
Deployment fails (naming, auth, timeout)	Deployment Errors	Azure deployment issue
Agent not appearing, MCP errors	Copilot Agents	Agent / tooling issue
Secret leaked in output or commit	Secrets	Credential leakage
Lint or link check fails	Validation	Linting / validation

Troubleshooting

Quick Diagnosis

Close

Symptom	Go to	Likely category
Can't log in to Azure, subscription not found	Azure CLI	Auth / subscription issue
RequestDisallowedByPolicy error	Policy Errors	Azure Policy denial
QuotaExceeded, region capacity errors	Quota Errors	Insufficient Azure quota
Container won't build, extensions missing	Dev Container	Environment setup issue
bicep build fails, module errors	Bicep	Template/syntax issue
Deployment fails (naming, auth, timeout)	Deployment Errors	Azure deployment issue
Agent not appearing, MCP errors	Copilot Agents	Agent / tooling issue
Secret leaked in output or commit	Secrets	Credential leakage
Lint or link check fails	Validation	Linting / validation

---

Dev Container

Docker won’t start

Symptoms: Docker Desktop fails to launch or reports an error on startup.

Fixes:

1. Windows: Ensure WSL 2 is enabled (wsl --install or wsl --update). Restart Docker Desktop after enabling WSL 2.
2. Mac: Check that virtualization is enabled in System Settings.
3. Restart Docker Desktop. If it still fails, try resetting to factory defaults.

Container fails to build

Symptoms: “Build failed” or timeout when reopening in container.

Fixes:

1. Ensure Docker Desktop is running and has at least 4 GB of RAM allocated
2. Run Dev Containers: Rebuild Container Without Cache from the Command Palette
3. Check your network; the build pulls images from mcr.microsoft.com

Extensions not loading

Symptoms: Copilot Chat or Bicep extension missing after container starts.

Fix: The recommended extensions are in .vscode/extensions.json. Run Extensions: Show Recommended Extensions and install any that are missing.

Azure CLI

az login fails inside Dev Container

Symptoms: Browser-based login does not redirect back.

Fix: Use device code flow:

az login --use-device-code

Subscription not found

Symptoms: Deployment fails with “subscription not found”.

Fixes:

1. List available subscriptions: az account list --output table
2. Set the correct one: az account set --subscription "<name-or-id>"

Bicep

bicep build fails with module errors

Symptoms: “Unable to restore module” or “module not found”.

Fixes:

1. Clear the Bicep module cache: bicep restore <file>
2. Ensure you have internet access (AVM modules are fetched from mcr.microsoft.com)
3. Check the module version exists: bicep publish errors often mean a typo in the version

Lint warnings about parameter descriptions

Symptoms: no-unused-params or missing-description warnings.

Fix: Every param must include a @description() decorator. Example:

@description('The Azure region for all resources.')
param location string = resourceGroup().location

Copilot Agents

Copilot not working

Symptoms: Copilot Chat is unresponsive or shows authentication errors.

Fixes:

1. Sign out of GitHub in VS Code and sign back in with the correct account
2. Reload VS Code (Developer: Reload Window)
3. Verify your Copilot subscription at github.com/settings/copilot
4. Open the current Accelerator agent files and confirm their declared models are permitted by your account or organization

Agent model is not available

Symptoms: An Accelerator agent cannot start because its declared model is unavailable.

Fixes:

1. Open the affected .github/agents/*.agent.md file and note its current model value.
2. Check your Copilot plan entitlements and organization model policy.
3. Ask the GitHub organization or enterprise owner whether that model is permitted.
4. Reload VS Code after policy changes.

Do not replace the model declaration only to make the error disappear. Compare your repository with the current Accelerator and ask the facilitator before changing an upstream-managed agent.

Agent not appearing in Chat

Symptoms: A main agent such as 01-Orchestrator does not appear in the agent picker.

Fixes:

1. Confirm that you opened the template-derived repository, not this documentation repository.
2. Confirm the repository is open in its Dev Container.
3. Verify the expected files exist under .github/agents/.
4. Reload VS Code with Developer: Reload Window.
5. Compare the repository with the current APEX Accelerator if files are missing.

Do not enable a legacy discovery setting as a substitute for loading the current repository configuration.

Agent produces incomplete output

Symptoms: Agent stops mid-response or skips steps.

Fixes:

1. Break large requests into smaller steps
2. Provide explicit file paths when referencing artifacts
3. Use 01-Orchestrator to identify the next main agent and proposed handoff; the human still selects and approves that handoff

MCP servers not working

Symptoms: A GitHub or Azure MCP server declared by the Accelerator returns an error or is unavailable.

Fixes:

1. Inspect .vscode/mcp.json in the template-derived repository and identify the failing server.
2. Preserve the exact startup or authentication error.
3. Confirm account and organization policy permits the declared server.
4. For Azure-backed tools, confirm the required Azure sign-in and subscription context.
5. Reload VS Code with Developer: Reload Window.
6. Compare your MCP configuration with the current APEX Accelerator.

The server list changes over time. Do not diagnose against the retired Azure Pricing, Draw.io, MS Learn, or Terraform list unless those servers are present in your current repository.

GitHub reference: Configure MCP server access

APEX reference: MCP server integration

Validation and Linting

Run the commands in this section from the root of your working repository created from the accelerator template, not from this documentation repo.

npm run lint:md fails

Symptoms: markdownlint reports errors.

Fix: Auto-fix most issues:

npm run lint:md:fix

For remaining issues, check .markdownlint-cli2.jsonc for the rule that fired.

npm run lint:links reports broken links

Symptoms: markdown-link-check finds dead links.

Fixes:

1. For internal links: verify the target file exists
2. For external links: check if the URL is behind authentication or geo-blocked
3. Add false positives to .markdown-link-check.json ignore patterns

Secrets and Credential Leakage

Secret appears in agent output or committed file

Symptoms: A connection string, access key, or password is visible in an agent-generated file or Git history.

Fixes:

1. Rotate the credential immediately — regenerate the key or password in the Azure portal or CLI
2. Replace the secret with a placeholder (<your-connection-string>) in the file
3. If already committed, remove from Git history or notify your facilitator
4. Use Key Vault references or environment variables going forward

Preventing secret leakage

• Never paste real secrets into Copilot Chat prompts
• Review all agent-generated files before committing
• Use az keyvault secret set to store secrets safely
• Use managed identities where possible to avoid secrets entirely

---

Policy Errors and Governance

RequestDisallowedByPolicy on deployment

Symptoms: Deployment fails with a policy violation error naming a specific policy.

Diagnosis:

1. Read the error message — it names the policy that denied the operation
2. Common MicroHack policies: required tags (Environment, Project), HTTPS-only, TLS 1.2, allowed locations

Fixes by policy type:

Policy denial	Fix
Missing Environment or Project tag	Add tags block to every resource in your Bicep
Storage not HTTPS-only	Set supportsHttpsTrafficOnly: true
Storage TLS version	Set minimumTlsVersion: 'TLS1_2'
Storage public blob access	Set allowBlobPublicAccess: false
SQL not Azure AD-only	Set azureADOnlyAuthentication: true
App Service not HTTPS	Set httpsOnly: true
Location not allowed	Deploy to swedencentral or germanywestcentral only

Policies not taking effect

Symptoms: Deployment succeeds but you expected a policy denial, or Get-GovernanceStatus.ps1 shows Unknown.

Fixes:

1. Azure Policies take 5–15 minutes to propagate after deployment
2. Ask your facilitator to run pwsh -File scripts/Get-GovernanceStatus.ps1 -Subscription "<subscription-name-or-id>" -MicrohackOnly to check activation status
3. If status is Unknown, wait 10 minutes and re-check
4. If still not active after 30 minutes, ask facilitator to re-run Setup-GovernancePolicies.ps1

Tip

Even if policies haven’t propagated yet, add the required tags and security settings to your Bicep — they are part of the success criteria.

Escalation

If you cannot resolve a policy error after checking the table above, ask your facilitator. Provide the full error message and the resource type you were deploying.

---

Quota Errors

QuotaExceeded on deployment

Symptoms: Deployment fails with quota or capacity error for a specific resource type or region.

Fixes:

1. Check current usage: az vm list-usage -l swedencentral -o table
2. Try a smaller SKU (e.g., S1 instead of P1v3)
3. Try the secondary region (germanywestcentral)
4. Delete unused resources from previous attempts
5. Ask your facilitator for help if no quota is available

---

Deployment Errors

NameNotAvailable or StorageAccountAlreadyTaken

Symptoms: Globally unique resource name is already in use.

Fix: Use uniqueString(resourceGroup().id) suffix pattern in your Bicep naming convention.

AuthorizationFailed during deployment

Symptoms: Deployment fails with permission error.

Fixes:

1. Verify you’re targeting the correct subscription: az account show
2. Re-authenticate: az login --use-device-code
3. Confirm you have Owner or Contributor role on the subscription

Deployment timeout or partial failure

Symptoms: Some resources create successfully, others fail or time out.

Fixes:

1. Check the deployment status in the Azure portal (Resource group → Deployments)
2. Look for the specific resource that failed and its error message
3. Preserve the exact error and escalate to the facilitator or the selected 07b-Bicep Deploy or 07t-Terraform Deploy agent. Participants must not substitute direct Azure CLI deployment for the approved agent path.

---

MicroHack-Specific

Governance policies not applying

Symptoms: Setup-GovernancePolicies.ps1 runs but policies don’t appear.

Fix: Policy assignments can take up to 30 minutes to propagate. Ask your facilitator to verify policy status with:

pwsh -File scripts/Get-GovernanceStatus.ps1 -Subscription "<subscription-name-or-id>" -MicrohackOnly