microsoft/aspire · error

ASPIRE_REMOTE_APPHOST_TOKEN environment variable is not set

Error message

ASPIRE_REMOTE_APPHOST_TOKEN environment variable is not set

What it means

During connect, after opening the socket to the AppHost, the client requires the ASPIRE_REMOTE_APPHOST_TOKEN environment variable for shared-secret authentication. If the variable is unset or empty the raw connection is closed immediately and this error (joined with any close error) is returned to CreateBuilder callers.

Solutions

1. Run the app via `aspire run` so Aspire injects ASPIRE_REMOTE_APPHOST_TOKEN into the process environment
2. Export the token manually for local runs: ASPIRE_REMOTE_APPHOST_TOKEN=<token from the AppHost session>
3. In containers/CI, pass the variable through (docker run -e / k8s env / workflow env) from the AppHost environment
4. Verify with `os.Getenv`/printenv in the failing process that the variable is actually visible

Example fix

// before
go run ./api  // fails: token env var not set

// after
export ASPIRE_REMOTE_APPHOST_TOKEN="$ASPIRE_REMOTE_APPHOST_TOKEN"  # or obtain from AppHost
export OTEL_EXPORTER_OTLP_ENDPOINT=...
go run ./api

if os.Getenv("ASPIRE_REMOTE_APPHOST_TOKEN") == "" {
	return errors.New("run via 'aspire run' or set ASPIRE_REMOTE_APPHOST_TOKEN")
}

When it happens

Trigger: CreateBuilder is called and the process environment lacks ASPIRE_REMOTE_APPHOST_TOKEN: launching the generated Go app directly with `go run`/`go build` outside `aspire run`; running in a shell that lost the env var; CI/container environments where the Aspire-injected variable was not propagated.

Common situations: Developers running the Go starter API standalone instead of via `aspire run`; Docker/Kubernetes deployments missing the env var; copying the env from a different AppHost session; the token var cleared by shell profile or dotenv misconfiguration.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• ASPIRE_REMOTE_APPHOST_TOKEN environment variable is not set.
• failed to authenticate to AppHost
• failed to authenticate to the AppHost server
• The Aspire extension token must be set if…
• -32000

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

Appendix: source

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

// 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)
	}

	return nil
}

// onDisconnect registers a callback to be invoked exactly once when the
// connection is closed.

View on GitHub (pinned to 25830f84bd)