MicrosoftKnown publishermicrosoft-foundry/foundry-agent-webapp/.github/skills/validating-local-setup/SKILL.md

validating-local-setup

Skill124 starsChanged 7 months agoMITView on GitHub

Diagnose and fix incomplete local development setup. Use when dev servers fail to start, env vars are missing, authentication errors occur, or before running any dev commands for the first time.

Reads credentials

In this repository20 other files it gives its agents.
- .github/copilot-instructions.mdCopilot instructions
- committing-codeSkill
- deploying-to-azureSkill
- implementing-chat-streamingSkill
- planning-featuresSkill
- researching-azure-ai-sdkSkill
- reviewing-documentationSkill
- syncing-mcp-serversSkill
- testing-cli-compatibilitySkill
- testing-with-playwrightSkill
- triaging-issuesSkill
- troubleshooting-authenticationSkill
- understanding-architectureSkill
- validating-deploymentsSkill
- validating-ui-featuresSkill
- writing-bicep-templatesSkill
- writing-csharp-codeSkill
- writing-typescript-codeSkill
- writing-unit-tests-csharpSkill
- writing-unit-tests-typescriptSkill

The file

We split this skill into the rules it gives an agent

10 rules. About 0 are common, 3 are distinctive, and 7 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
If you came from the portal, paste those values and run azd up — it detects them and incorporates them automatically.
line 21
Distinctive:
Run the validation script to check all configuration:
line 25
Very specific:
Fix: Run azd up — this creates the Entra app and generates frontend/.env.local.
line 73
Very specific:
Fix: Run azd up, then restart the dev server.
line 81
Very specific:
Fix: Ensure AzureAd__ClientId matches the Entra app registration.
line 85
Distinctive:
Restart dev servers: after any fix — env vars are read at startup.
line 113
Very specific:
Before executing dotnet watch run, npm run dev, or start-local-dev.ps1:
line 117
Very specific:
Check if frontend/.env.local exists
line 119
Very specific:
If either is missing, tell the user to run azd up first
line 121
Distinctive:
Do NOT try to create these files manually — they contain auto-generated Entra app registration IDs
line 122

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

SKILL.md

Local Setup Validation

Portal vs `azd up` — What Each Provides

The AI Foundry portal's "View sample app code" gives you AI resource variables (AI_AGENT_ENDPOINT, AI_AGENT_ID), which identify your agent. However, this app also needs an Entra ID app registration for user authentication — which only azd up creates. Both sets of config are required.

Source	What It Provides	Config It Generates
AI Foundry portal	Agent endpoint + agent ID	Root `.env` (or manual `azd env set`)
`azd up`	Entra app registration, RBAC, infrastructure	`frontend/.env.local` + `backend/WebApp.Api/.env`

If you came from the portal, paste those values and run azd up — it detects them and incorporates them automatically.

Quick Diagnostic

Run the validation script to check all configuration:

pwsh -File deployment/scripts/validate-config.ps1

This checks for frontend/.env.local and backend/WebApp.Api/.env with the core authentication variables. For a full list of required variables, see the tables below.

What `azd up` Creates

This app requires azd up before local development works. Here's what it provisions:

What	Why	Generated File
Entra ID app registration	SPA authentication (MSAL.js)	`frontend/.env.local`
Backend auth config	JWT token validation	`backend/WebApp.Api/.env`
Azure infrastructure	Container Apps, ACR, RBAC	`.azure/<env>/.env`
Redirect URIs	Login callback URLs	Entra app registration

Even if AI Foundry resources already exist (e.g., from the portal "View sample app code" flow), azd up is still required to create the Entra app registration.

Required Environment Variables

Frontend (`frontend/.env.local`)

Variable	Source	Required
`VITE_ENTRA_SPA_CLIENT_ID`	Entra app registration (created by `azd up`)	Yes
`VITE_ENTRA_TENANT_ID`	Azure AD tenant	Yes
`VITE_ENTRA_BACKEND_CLIENT_ID`	Backend app registration (OBO mode only)	No

Backend (`backend/WebApp.Api/.env`)

Variable	Source	Required
`AzureAd__TenantId`	Azure AD tenant	Yes
`AzureAd__ClientId`	Entra app registration	Yes
`AzureAd__Audience`	`api://{ClientId}`	Yes
`AI_AGENT_ENDPOINT`	AI Foundry project endpoint	Yes
`AI_AGENT_ID`	Agent name in Foundry	Yes

Common Error Patterns

"undefined" in login URL

login.microsoftonline.com/undefined/oauth2/v2.0/authorize?client_id=undefined

Cause: VITE_ENTRA_SPA_CLIENT_ID and VITE_ENTRA_TENANT_ID not set. Fix: Run azd up — this creates the Entra app and generates frontend/.env.local.

AADSTS900023: Specified tenant identifier is neither a valid DNS name

Cause: Same as above — tenant ID is undefined or empty. Fix: Run azd up.

Frontend shows "Setup Required" error page

Cause: The Vite env check plugin detected missing environment variables. Fix: Run azd up, then restart the dev server.

401 Unauthorized on /api/* endpoints

Cause: Backend JWT validation failing — check backend/WebApp.Api/.env. Fix: Ensure AzureAd__ClientId matches the Entra app registration. Run azd provision to regenerate.

ManagedIdentityCredential error in local dev

Cause: Backend trying to use managed identity locally. Fix: Set ASPNETCORE_ENVIRONMENT=Development — local dev uses ChainedTokenCredential(AzureCliCredential, AzureDeveloperCliCredential) instead.

Step-by-Step Fix for Incomplete Setup

Check current state:

pwsh -File deployment/scripts/validate-config.ps1

If no .azure/ directory (never ran azd):
```
azd up
```

If .azure/ exists but env files missing (partial setup):

azd provision   # Re-creates Entra app + generates .env files

If env files exist but vars are wrong (stale config):
```
azd provision   # Regenerates everything
```
Restart dev servers after any fix — env vars are read at startup.

For Agents: Before Running Dev Commands

Before executing dotnet watch run, npm run dev, or start-local-dev.ps1:

Check if frontend/.env.local exists
Check if backend/WebApp.Api/.env exists
If either is missing, tell the user to run azd up first
Do NOT try to create these files manually — they contain auto-generated Entra app registration IDs

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free