{"record":{"id":"fbbafcb05bb257a4","repo":"microsoft/aspire","slug":"aspire-remote-apphost-token-environment-variable-is-not-set-fbbafc","errorCode":null,"errorMessage":"ASPIRE_REMOTE_APPHOST_TOKEN environment variable is not set","messagePattern":"ASPIRE_REMOTE_APPHOST_TOKEN environment variable is not set","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting.CodeGeneration.Go/Resources/transport.go","lineNumber":633,"sourceCode":"// background reader and writer goroutines.\nfunc (c *client) connect(ctx context.Context, timeout time.Duration) error {\n\tc.mu.Lock()\n\tif c.conn != nil {\n\t\tc.mu.Unlock()\n\t\treturn nil\n\t}\n\n\trawConn, err := openConnection(c.socketPath, timeout)\n\tif err != nil {\n\t\tc.mu.Unlock()\n\t\treturn fmt.Errorf(\"failed to connect to AppHost: %w\", err)\n\t}\n\n\tauthToken := os.Getenv(\"ASPIRE_REMOTE_APPHOST_TOKEN\")\n\tif authToken == \"\" {\n\t\tcErr := rawConn.Close()\n\t\tc.mu.Unlock()\n\t\treturn errors.Join(errors.New(\"ASPIRE_REMOTE_APPHOST_TOKEN environment variable is not set\"), cErr)\n\t}\n\n\tconn := newConnection(rawConn, c, c.onConnectionClose)\n\tc.conn = conn\n\tc.mu.Unlock()\n\n\tconn.start()\n\n\tif err := c.authenticate(ctx, authToken); err != nil {\n\t\tc.disconnect()\n\t\treturn fmt.Errorf(\"failed to authenticate to AppHost: %w\", err)\n\t}\n\n\treturn nil\n}\n\n// onDisconnect registers a callback to be invoked exactly once when the\n// connection is closed.","sourceCodeStart":615,"sourceCodeEnd":651,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting.CodeGeneration.Go/Resources/transport.go#L615-L651","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Run the app via `aspire run` so Aspire injects ASPIRE_REMOTE_APPHOST_TOKEN into the process environment","Export the token manually for local runs: ASPIRE_REMOTE_APPHOST_TOKEN=<token from the AppHost session>","In containers/CI, pass the variable through (docker run -e / k8s env / workflow env) from the AppHost environment","Verify with `os.Getenv`/printenv in the failing process that the variable is actually visible"],"exampleFix":"// before\ngo run ./api  // fails: token env var not set\n\n// after\nexport ASPIRE_REMOTE_APPHOST_TOKEN=\"$ASPIRE_REMOTE_APPHOST_TOKEN\"  # or obtain from AppHost\nexport OTEL_EXPORTER_OTLP_ENDPOINT=...\ngo run ./api","handlingStrategy":"validation","validationCode":"if os.Getenv(\"ASPIRE_REMOTE_APPHOST_TOKEN\") == \"\" {\n\treturn errors.New(\"run via 'aspire run' or set ASPIRE_REMOTE_APPHOST_TOKEN\")\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always start the Go app through `aspire run`","Propagate ASPIRE_REMOTE_APPHOST_TOKEN through Docker/K8s/CI env","Check the env var at startup with a clear fail-fast message","Don't copy tokens across AppHost sessions"],"tags":["go","environment","authentication","apphost","configuration"],"backgroundTag":"missing-env-var","analyzedSha":"25830f84bd145686607ad00c057b3f84e2e51d43","analyzedAt":"2026-09-16T11:10:06.193Z","contentChangedAt":"2026-09-16T11:10:06.193Z","schemaVersion":2},"datasetVersion":"2026-09-21T04:17:39.646Z"}