Troubleshooting

Single-page articles for common Forge errors. Each article covers exactly one issue: the exact error text, why it happens, the smallest fix, and how to verify it worked.

Can't find your error?

Search for the exact error text first. If nothing matches, check the version compatibility matrix, then report it with the common issue form so it can become an article. Check an article's applicability and safety notes before running its fix.

Find an article

Browse the generated article catalog for every article with its ID and components, or browse by tag to find related articles, such as everything tagged aspire or pipelines.

Every page in this section except this one and the catalog is a single-symptom article with a SAIFTRBL identifier. The identifier is a stable handle; the readable filename remains the canonical page URL. Every article also answers at troubleshoot/<ID>/, which redirects to the readable page. For example, troubleshoot/SAIFTRBL0012/ opens SAIFTRBL0012. Share or bookmark the ID URL when you want a link that survives article renames.

How articles get created

Anyone can add an article. In the Forge repository, ask Copilot to "create a troubleshooting article from this" with a diagnosed GitHub issue, Teams-relayed report, or Azure DevOps work item. The repo-local create-troubleshooting-article skill starts from the template, checks for an existing article to update instead, and prepares a PR.

Writing one by hand? Copy the template, follow the answer-first author guidance, and keep one issue per article.

Follow the identifier allocation rules when adding an article. That contract owns the global append-only sequence and retired-ID checks. Troubleshooting IDs identify articles, not compiler diagnostics; existing diagnostic identifiers and URLs remain unchanged.

The common issue form is the fast path, not the only one: the troubleshooting-candidate label is a triage outcome, and applying it to any existing bug or support issue marks it as article material just the same.

Required tags

Browse by tag under Reference to find related troubleshooting articles and other Forge documentation. The authoring contract also lives under Reference.

Every article must declare frontmatter tags: with troubleshooting plus at least one component tag from this vocabulary:

Tag	Covers
aspire	Aspire CLI, AppHost, local orchestration
authentication	401/403, token validation, Entra, Okta
build	restore, compile, packaging, codegen
typespec	TypeSpec compiler, API generation
cosmos-db	Cosmos DB config, connectivity, integration
cors	browser-origin and preflight failures
pipelines	Azure DevOps pipeline failures
terraform	Terraform modules and infrastructure
cli	saif CLI errors
templates	dotnet new template scaffolding issues

If no tag fits, add the article and the new tag to this table in the same PR.