Troubleshoot SwarmCraft

Treat a blocking message as a boundary to resolve, not something to bypass. Retry only after checking the stage that failed.

Setup and connection recovery

• Unsupported environment: use supported macOS or x86-64 Windows 11 23H2 or later. On a managed or unsupported machine, ask the administrator whether the Manual setup checklist is allowed.
• Existing tool detected: do not remove or downgrade it to force an install. Setup preserves working tools, VS Code profiles, settings, extensions, Git configuration, credential helpers, and PATH order.
• Elevation, vendor prompt, or restart: finish or cancel the operating-system prompt. Restart when requested, reopen Setup, and let it re-detect before applying anything else.
• Offline or verification failure: restore network access and retry. Do not bypass a checksum, code-signing, publisher, Gatekeeper, or Authenticode failure.
• GitHub CLI authorization: use the exact browser opened by Setup. Paste its one-time code only there. If the account is wrong, return to Change account; never paste a token into Setup or diagnostics.
• Insecure credential storage: repair the operating-system credential store or GitHub CLI configuration, then authenticate again. Setup will not hand off an insecure active account.
• Provider selection: after VS Code opens, run SwarmCraft: Choose AI Provider and select an installed, signed-in provider. Provider readiness is separate from machine readiness.
• Browser sign-in did not return: keep the initiating VS Code window open, complete the browser approval, then return to that same window. Run SwarmCraft: Sign In again if the one-time handoff expired.
• Environment is not ready: rerun Setup. It inspects live state and proposes only remaining work; a completed action does not need to be repeated.
• Docker needs attention: Docker is optional until the project requires containers. On Windows, restart after WSL 2 or virtualization changes before re-detection.
• Partial success or cancellation: read the current diagnostic, resolve it, and rerun. Completed work is preserved.

If a signed release still cannot repair the machine, collect only the redacted diagnostic codes shown by Setup and contact SwarmCraft support. Do not include installer output, credentials, browser codes, personal paths, or private repository content.

Project connection failed

Confirm the intended SwarmCraft account, GitHub host, SwarmCraft VS Code profile, and workspace folder. A ready environment does not bind a project automatically. Deep Discovery binds one local Git workspace before project creation; a generated project connects to its delivery repository afterward.

Deep Discovery is not enabled for this account

The route is in a limited account-enabled rollout. Confirm you are signed into the intended account and API environment. If the message remains, read the public guide, prepare only non-sensitive local material you control, and contact support about pilot access. Reinstalling the extension or calling the CLI directly cannot bypass eligibility.

The workspace is not ready

• Open exactly one trusted Git workspace folder.
• If Git is missing, install it and restart VS Code.
• If the folder is not a repository, accept the local initialization offer or run git init yourself.
• A remote, protected default branch, first commit, and clean working tree are not required to start.
• In a multi-root window, select the exact folder before starting or resuming.

Codex or Copilot is unavailable

Confirm the selected provider is installed, signed in, and usable in its own chat. Run SwarmCraft: Choose AI Provider to select the provider that is actually ready. Provider usage is needed for discovery and review, not package preparation.

The sidebar is missing or stale

Run SwarmCraft: Resume Deep Discovery. Check VS Code notifications and use SwarmCraft: Show Output when support needs the content-safe extension log. Reload the window after upgrading the extension.

A source needs attention

• Binary originals require a reviewed Markdown sidecar; the binary is never packaged.
• Changed, missing, or stale selected sources must be corrected and the complete set confirmed again.
• Remove secrets or unsupported file types instead of asking AI to disguise them.
• Source-selection changes invalidate the previous package.

A discovery document blocks preparation

Open the lifecycle row named in the message. Finish owner review, resolve placeholders or open decisions, or use a justified NOT_APPLICABLE state. Supporting sources cannot substitute for a missing curated decision.

The package is too large or exceeds the token budget

Do not truncate or summarize reviewed material silently. Remove irrelevant supporting sources through explicit selection, resolve duplicated source material, or narrow the discovery scope. Curated documents remain required. Prepare again and review the new digest.

Upload was interrupted

Use Prepare Discovery Package Again only when preparation or transport failed before admission. Reopen the preview and authorize the current digest. Once a package is admitted, recover it from Discoveries rather than creating competing snapshots.

Project generation failed

Use Try project creation again for a retryable failure. The settled orchestration charge, completed generation checkpoints, and admitted package remain safe. For Support needed, open the authenticated support workspace. Do not approve the fixed charge again, upload a modified package, or paste discovery content into a general support message.

For CLI diagnostics, create the content-safe package support bundle requested by support:

swarmcraft discovery support-bundle --workspace . --run <run-id>

The bundle excludes document text and source paths. Review it before sharing.

Delivery or CLI run failed

• Board and packet disagree: refresh the board, open the current packet, and resolve a stale revision before retrying. Do not edit task identity or lane frontmatter by hand.
• Provider command failed: verify the selected Codex or Copilot CLI works directly, or review the custom command. Keep API keys out of command arguments.
• Build or check failed: leave the task in Doing or Checking, record the exact failure, fix it, and rerun the same check.
• Dirty repository blocked one-shot: inspect git status --short. Commit or stash only changes you understand; use --allow-dirty only when the overlap is intentional.
• Request budget ended: inspect the run manifest, then resume with a reviewed higher --max-agent-requests value if more work is justified.
• Managed AI needs credits: add credits in Billing and resume the same run. Completed tasks and checkpoints remain intact.
• Commit succeeded but Done failed: refresh the board and retry the lane transition after fixing the reported blocker. Do not create a second commit.

For a one-shot failure, generate swarmcraft support-bundle --run <run-id> --workspace ., review its redacted contents, and attach only the requested files to SwarmCraft support.

Deployment failed

Stop promotion when configuration, secrets, migration, health, functional verification, or monitoring evidence is incomplete. Use the release's reviewed rollback trigger and artifact. If data changes are not reversible, follow the documented forward-recovery path and involve the service and data owners. SwarmCraft cannot operate or repair customer infrastructure.