Reference

Troubleshooting

Known issues with copy-paste fixes, plus versioning and repository notes.

Common issues

First apm install takes 30+ minutes (but never errors)

Almost always GitHub API rate limiting. This package references hundreds of individual files from microsoft/hve-core, and APM fetches each one over GitHub's HTTP path. Unauthenticated callers are capped at 60 requests/hour; once the cap is hit APM waits for the window to reset (honoring GitHub's Retry-After header) and keeps going, so the install crawls instead of failing. A fresh machine also has a cold APM cache, so every file is fetched.

Authenticate before installing to raise the limit to 5,000 requests/hour:

gh auth login            # recommended — APM picks it up automatically
# or set a token (public read is enough; hve-core is public)
$env:GITHUB_TOKEN = "ghp_xxx"
apm install "Peter-N91/hve-squad#vX.Y.z" --target copilot

APM's GitHub token precedence is GITHUB_APM_PAT_<ORG> → GITHUB_APM_PAT → GITHUB_TOKEN → GH_TOKEN → gh auth token → your git credential helper. Once authenticated the install completes quickly, and the warm cache makes later installs near-instant.

Raising --parallel-downloads does not help an unauthenticated install — the cap is per hour, so more concurrency just reaches it faster.

A few packages fail with HTTP 502 (or 503) — Failed to download virtual package

[x] 2 packages failed:
    +- hve-core-github-execute-backlog -- Failed to download virtual package:
       Failed to download .github/prompts/github/github-execute-backlog.prompt.md: HTTP 502

This is a transient GitHub server error, not a problem with your manifest or pins. 502 Bad Gateway (and 503) mean GitHub's file endpoint briefly failed to respond while APM was fetching one of the hundreds of individual files this package references. The tell-tale sign it is transient: only a handful of packages fail while the rest succeed, and they fail on the download step even though the pin resolved fine.

Just run the install again — cached files are skipped, so only the missing packages are retried:

apm install

Do not confuse this with 404 / "File not found (tried refs: main, master)", which means a file no longer exists at that ref (upstream drift or a bad pin), or with the slow-but-never-erroring rate-limit case above. If 502s persist across several retries, GitHub itself may be degraded — check githubstatus.com. Authenticating first (gh auth login) also makes installs more resilient.

[x] No harness detected after apm install (APM 0.18.0+)

APM downloaded the sources into apm_modules/ but skipped the deploy step because no harness marker was found in your project (no .github/agents/, .github/prompts/, .claude/, .cursor/, etc.). Re-run with --target copilot: 

apm install "Peter-N91/hve-squad#vX.Y.z" --target copilot

Or add a targets: block to your project's apm.yml so future installs work without the flag (see Getting Started → Option B).

apm_modules/ populated but .github/ is empty and no error visible

Same root cause as above — scroll up in your terminal for the No harness detected message and apply the --target copilot fix.

No scripts found

Check the scripts block in apm.yml and run apm list.

Access failures to HVE Core

Confirm git authentication and repository visibility.

Dependencies look stale

Run apm run sync-deps, then apm lock.

A role never produces its artifact, or the coordinator quietly “reroutes” to another agent

Symptoms: a stage reports blocked and the run continues anyway; no history/<agent>.md entry for that role; later gates pass without evidence. The usual cause is a roster row whose Primary cannot accept a role-scoped dispatch — either the agent is no longer deployed after an HVE Core upgrade, or it is a delegated worker that refuses to act without a full input contract. Both look identical at run time.

Check the role’s Primary in .copilot-tracking/squad/team.md against the cast catalog in .github/instructions/squad/squad-roster.instructions.md, and confirm the agent file exists under .github/agents/. A role whose Deliverable Root its Primary cannot write is always a wrong row. After any hve-core bump, re-run apm install and compare the cast with scripts/Get-HveCoreCastDelta.ps1.

.github still appears in git status after ignoring

Run git rm -r --cached .github once, then git add .github/workflows (if you track workflows here), then commit.

Azure-icon diagrams (HLD/LLD) won't render

When the Squad Azure Architect produces a committed PNG/SVG with real Azure icons via the python-diagrams skill, the render needs both Python and the Graphviz dot binary. On a typical Windows dev box two things commonly block it:

Verify the toolchain before authoring with the skill's checker: uv run --with diagrams python .github/skills/python-diagrams/scripts/verify_installation.py. If the diagram still won't render and you only need a quick visual, the architect falls back to an inline Mermaid diagram automatically.

Versioning

Notes