microsoft/aspire · critical

failed to connect to AppHost

Error message

failed to connect to AppHost: %w

What it means

CreateBuilder → connect attempts a socket connection to the Aspire AppHost (openConnection on c.socketPath). When the socket connection cannot be established, the underlying error is wrapped as "failed to connect to AppHost: %w". This is the Go-codegen equivalent of "AppHost not running or unreachable".

Solutions

1. Start the app through `aspire run` (or start the AppHost) so the socket exists before connecting.
2. Check the ASPIRE socket path environment variable is set and points to the live socket; print the wrapped err for details (permission refused vs no such file vs timeout).
3. If the AppHost is slow, increase the connection timeout.
4. Delete stale socket files from previous crashed runs and retry.

Example fix

// before
// go run ./api  ->  failed to connect to AppHost: dial unix /tmp/aspire.sock: connect: no such file or directory
// after
if os.Getenv("ASPIRE_APPHOST_ENDPOINT") == "" && os.Getenv("ASPIRE_REMOTE_APPHOST_TOKEN") == "" {
    log.Fatal("not launched by AppHost; use `aspire run` instead of running this project directly")
}

sock := os.Getenv("ASPIRE_APPHOST_ENDPOINT") // or the socket path var your runtime uses
if sock == "" {
    log.Fatal("not launched via `aspire run`; AppHost socket unavailable")
}
if _, err := os.Stat(sock); err != nil {
    log.Fatalf("AppHost socket %q not present: %v", sock, err)
}

app, err := aspire.CreateBuilder(ctx)
if err != nil {
    log.Fatalf("cannot reach AppHost (is `aspire run` active?): %v", err)
}

When it happens

Trigger: Running the generated app with `aspire run` missing (no AppHost process listening on the unix/named-pipe socket), wrong ASPIRE socket path env var, socket file removed, or connection timeout expiring because the AppHost is slow to start.

Common situations: Running the Go project directly (go run / IDE) instead of through the AppHost; AppHost crashed; permission denied on the socket file; Docker/WSL path mismatch; stale socket from a previous run.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• failed to authenticate to AppHost
• -32000
• aspire: dict getter returned unexpected type %T
• aspire: dict.toObject: unexpected result type %T
• aspire: list getter returned unexpected type %T

AI-assisted analysis of microsoft/aspire@25830f84bd (2026-09-16). Data as JSON: /api/errors/0f8384b8a946d975. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Hosting.CodeGeneration.Go/Resources/transport.go:626

		<-token.ctx.Done()
		c.cancelToken(id)
	}()
	return id
}

// connect establishes the connection to the AppHost server and starts the
// background reader and writer goroutines.
func (c *client) connect(ctx context.Context, timeout time.Duration) error {
	c.mu.Lock()
	if c.conn != nil {
		c.mu.Unlock()
		return nil
	}

	rawConn, err := openConnection(c.socketPath, timeout)
	if err != nil {
		c.mu.Unlock()
		return fmt.Errorf("failed to connect to AppHost: %w", err)
	}

	authToken := os.Getenv("ASPIRE_REMOTE_APPHOST_TOKEN")
	if authToken == "" {
		cErr := rawConn.Close()
		c.mu.Unlock()
		return errors.Join(errors.New("ASPIRE_REMOTE_APPHOST_TOKEN environment variable is not set"), cErr)
	}

	conn := newConnection(rawConn, c, c.onConnectionClose)
	c.conn = conn
	c.mu.Unlock()

	conn.start()

	if err := c.authenticate(ctx, authToken); err != nil {
		c.disconnect()
		return fmt.Errorf("failed to authenticate to AppHost: %w", err)

View on GitHub (pinned to 25830f84bd)