Troubleshooting your connection

If the dashboard shows This page couldn’t be loaded, check your internet connection, then choose Reload page. If reloading does not help, clear your browser’s cache. Choose Go home to return to your starting page instead.

When you open another dashboard page, Loading page… means it is still loading. Your current page stays visible until the next page is ready.

Open the Help center to read setup and troubleshooting guides without signing in. You can read a guide even when JavaScript is disabled in your browser.

Enable JavaScript to use search, copy buttons and theme controls. The workspace dashboard also needs JavaScript and your sign-in. If you enabled it after opening a page, reload the page before trying a control again.

Your copy of the sample is from an older preview. Installing a newer package or restarting Aspire does not rewrite the sample’s Program.cs. Download the current sample into a new folder, then follow Your first tunnel with Aspire.

Check that the requested package version is published and that your NuGet sources include nuget.org. If the version is available, refresh a potentially stale cached response. Run this from samples/AspireQuickstart, then start Aspire again:

dotnet restore AppHost/AppHost.csproj --source https://api.nuget.org/v3/index.json --no-http-cache

Check samples/Directory.Packages.props in the downloaded repository references 0.4.0-preview.7; the quickstart inherits its package versions from that parent folder. A release that is still being indexed can take a few minutes to appear.

Check the tunnel name is exact and the key belongs to that tunnel. Rotating a key replaces every other key, a revoked key never works again, and your sign-in password never works as a key.

• Aspire: stop the AppHost. Check the name in WithGroundhogTunnel, then use Manage User Secrets on your AppHost project to correct Parameters:groundhog-<tunnel name>-key. The explicit AddGroundhogTunnel form uses the secret parameter you declared instead. Start again, and never share the secrets file.
• CLI: set GROUNDHOG_KEY to the new key in the same terminal and run the command again. Exit code 3 means the key was rejected or the tunnel does not exist.

1. 1Open your app’s local address first, and fix any errors there before you test the public address.
2. 2Check the Groundhog client is still running and the tunnel shows Connected in the dashboard.
3. 3Copy the public address from the tunnel’s page. It is not the same as the service address.
4. 4Read the tunnel’s console in Aspire, or run the CLI with --verbose. Forwarding errors usually point to a wrong local port or an untrusted local HTTPS certificate.

Your app can be Running while the tunnel is still Connecting or Reconnecting: check your internet connection and check the Groundhog service is reachable. A second client that connects the same tunnel replaces the first, so run only the one you mean to.

If the client reports Agent connection capacity is full, the workspace or service has reached its agent-connection ceiling. The client backs off and retries automatically. Stop unused clients or reduce their connection pool size; an existing session stays connected when its replacement is refused at capacity.

If the client reports Agent admission capacity is full, too many connection checks are in progress. Let the client back off and retry automatically. Repeatedly restarting it adds more checks and does not reserve a slot.

If the client reports Connection address capacity is full, the service is tracking too many different connection addresses. Let the client back off and retry after the reported delay. Changing keys or repeatedly restarting does not free that shared capacity.

To tell your app’s own errors from forwarding errors, see Tell app errors from forwarding errors.

A Groundhog 503 busy response means the tunnel, your workspace or the service has reached its concurrent-request capacity. Reduce simultaneous requests and long-running streams, then retry with a delay. Creating another tunnel in the same workspace does not bypass its shared limit. Open WebSockets and streaming responses occupy capacity until they end. Groundhog sets these limits; capacity is best effort.

A Groundhog 429 response means your workspace or the service has reached its request-rate limit. Wait for the delay in the Retry-After response header before trying again. Reduce repeated polling and automatic retries; creating another tunnel in the same workspace shares the same request budget. Your app can also return its own 429 response. If the source is unclear, check your app’s logs or contact Groundhog support.

Your workspace shares a limit on stored tunnels. Disconnected tunnels still count. Delete a tunnel you no longer need, then create the new one. Renaming a tunnel or rotating its key keeps the same slot.

A change that is still finishing can also count against the limit. Refresh the tunnel list before retrying. If the workspace still cannot create a tunnel, contact Groundhog support about its limit.

Share your client version, the exact error text and the step that failed. Remove connection keys and private request content first.