Add dashboard troubleshooting page

src/frontend/config/sidebar/dashboard.topics.ts

@@ -243,6 +243,27 @@ export const dashboardTopics: StarlightSidebarTopicsUserConfig = {
       },
       slug: 'dashboard/security-considerations',
     },
+    {
+      label: 'Troubleshooting',
+      translations: {
+        da: 'Fejlfinding',
+        de: 'Fehlerbehebung',
+        en: 'Troubleshooting',
+        es: 'Solución de problemas',
+        fr: 'Dépannage',
+        hi: 'समस्या निवारण',
+        id: 'Pemecahan masalah',
+        it: 'Risoluzione dei problemi',
+        ja: 'トラブルシューティング',
+        ko: '문제 해결',
+        'pt-BR': 'Solução de problemas',
+        ru: 'Устранение неполадок',
+        tr: 'Sorun giderme',
+        uk: 'Усунення неполадок',
+        'zh-CN': '故障排除',
+      },
+      slug: 'dashboard/troubleshooting',
+    },
     {
       label: 'Telemetry',
       translations: {

src/frontend/src/content/docs/dashboard/troubleshooting.mdx

@@ -0,0 +1,65 @@
+---
+title: Troubleshoot the Aspire dashboard
+description: Diagnose and resolve common Aspire dashboard issues including connection errors between the dashboard and the app host resource service.
+---
+
+import { Steps } from '@astrojs/starlight/components';
+import LearnMore from '@components/LearnMore.astro';
+
+This article helps you diagnose and resolve common issues with the Aspire dashboard.
+
+## Connection errors between the dashboard and app host
+
+The dashboard displays resource information by connecting to a gRPC resource service hosted by the app host. When this connection fails, the dashboard may show an error message or display telemetry data without any resource list or console logs.
+
+### Symptoms
+
+- The dashboard loads but shows no resources in the resource list.
+- Console logs are unavailable for resources.
+- An error banner appears indicating the dashboard can't connect to the resource service.
+- The dashboard log contains errors related to gRPC connection failures.
+
+### Viewing dashboard logs
+
+Enable verbose logging to get more detail about connection failures. Run the app host with debug-level output:
+
+```bash title="Run with debug output"
+aspire run --log-level Debug
+```
+
+Review the console output for messages related to the resource service connection, such as gRPC status codes or TLS handshake failures.
+
+### Certificate and TLS errors
+
+When running with HTTPS, the dashboard and app host use certificates to secure the gRPC connection. Certificate issues are a common source of connection failures.
+
+**Common causes:**
+
+- The development certificate isn't trusted. Run `aspire certs trust` to trust the development certificate.
+- The certificate has expired or is corrupted. Regenerate it with `aspire certs clean` followed by `aspire certs trust`.
+- A custom certificate is specified but the file path or password is incorrect. Verify the `Dashboard:ResourceServiceClient:ClientCertificate` settings.
+
+### Firewall and network issues
+
+- Confirm that a firewall or security software isn't blocking the connection between the dashboard and the resource service endpoint.
+- The resource service uses gRPC, which requires HTTP/2. Some firewalls, proxies, or network appliances don't support HTTP/2 traffic and may silently drop or downgrade the connection. Ensure that any intermediary between the dashboard and the app host allows HTTP/2.
+
+### Ping timeout errors when debugging the app host
+
+You may see the following error in the dashboard:
+
+```
+Status(StatusCode="Internal", Detail="Error starting gRPC call.
+HttpRequestException: The HTTP/2 server didn't respond to a ping request
+within the configured KeepAlivePingDelay. (HttpProtocolError)")
+```
+
+This means the dashboard's gRPC client sent an HTTP/2 PING frame to the app host's resource service, but didn't receive a response in time.
+
+The most likely cause is that a debugger is paused on the app host — when you hit a breakpoint, the process can't respond to HTTP/2 PING frames, triggering the timeout. This error resolves once execution resumes.
+
+If you see this error and you're running without a debugger attached, verify the app host process is still alive and responsive.
+
+<LearnMore>
+For the full list of configuration options, see [Aspire dashboard configuration](/dashboard/configuration/).
+</LearnMore>