// 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.
| name | validating-local-setup |
| description | 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. |
azd up — What Each ProvidesThe 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.
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.
azd up CreatesThis 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.
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/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 |
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.
Cause: Same as above — tenant ID is undefined or empty.
Fix: Run azd up.
Cause: The Vite env check plugin detected missing environment variables.
Fix: Run azd up, then restart the dev server.
Cause: Backend JWT validation failing — check backend/WebApp.Api/.env.
Fix: Ensure AzureAd__ClientId matches the Entra app registration. Run azd provision to regenerate.
Cause: Backend trying to use managed identity locally.
Fix: Set ASPNETCORE_ENVIRONMENT=Development — local dev uses ChainedTokenCredential(AzureCliCredential, AzureDeveloperCliCredential) instead.
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.
Before executing dotnet watch run, npm run dev, or start-local-dev.ps1:
frontend/.env.local existsbackend/WebApp.Api/.env existsazd up firstProvides deployment commands and troubleshooting for Azure Container Apps. Use when running azd commands, deploying containers, debugging deployment failures, or updating infrastructure in this repository.
Provides SSE streaming patterns for the chat API and frontend. Use when implementing or modifying chat streaming, handling SSE events, or troubleshooting message flow between frontend and backend.
Provides research patterns for Foundry Agent Service SDK. Use when implementing agent features, looking up SDK methods, finding code samples, or troubleshooting Azure.AI.Projects API usage.
Provides architecture overview with state machines, SSE event flow, and file mappings. Use when understanding system design, debugging state issues, or maintaining ARCHITECTURE-FLOW.md.
Provides C# and ASP.NET Core coding standards for this repository. Use when writing or modifying C# code, implementing API endpoints, configuring middleware, or working with authentication in the backend.
Provides TypeScript and React coding standards for this repository. Use when writing or modifying TypeScript code, creating React components, implementing MSAL authentication, or working with the frontend.