microsoft/aspire · error · ValueError

ASPIRE_REMOTE_APPHOST_TOKEN environment variable not set…

Error message

ASPIRE_REMOTE_APPHOST_TOKEN environment variable not set. Run this application using `aspire run`.

What it means

After connecting over the socket, the Python remote client must authenticate using the ASPIRE_REMOTE_APPHOST_TOKEN environment variable provisioned by `aspire run`. Missing token raises ValueError before `client.authenticate` can run.

Solutions

Run via `aspire run` so both env vars are set together.
Export ASPIRE_REMOTE_APPHOST_TOKEN with the AppHost-issued token when launching manually.
Audit the launcher's env filtering to ensure ASPIRE_REMOTE_APPHOST_TOKEN is propagated.
Fix container/manifest env definitions to include the token alongside the socket path.

Example fix

# before
env = {"REMOTE_APP_HOST_SOCKET_PATH": socket}
subprocess.run(["python", "app.py"], env=env)
# after
env = {"REMOTE_APP_HOST_SOCKET_PATH": socket, "ASPIRE_REMOTE_APPHOST_TOKEN": token}
subprocess.run(["python", "app.py"], env=env)

Defensive patterns

Strategy: validation

Validate before calling

import os
if not os.environ.get("ASPIRE_REMOTE_APPHOST_TOKEN"):
    raise SystemExit("launch with `aspire run` (missing ASPIRE_REMOTE_APPHOST_TOKEN)")

Type guard

def is_authenticated_env() -> bool:
    return bool(os.environ.get("ASPIRE_REMOTE_APPHOST_TOKEN"))

Try / catch

try:
    client = connect_aspire()
except ValueError:
    raise SystemExit("ASPIRE_REMOTE_APPHOST_TOKEN missing; run via `aspire run` or export the token")

Prevention

Set both socket path and token env vars together when launching manually.
Audit supervisors/containers for env filtering that drops ASPIRE_REMOTE_APPHOST_TOKEN.
Prefer `aspire run` over manual exports.

When it happens

Trigger: The socket env var is present but ASPIRE_REMOTE_APPHOST_TOKEN is unset: process launched with only partial env inheritance, token stripped by a sanitizer, or a different launcher used for the child process.

Common situations: Custom process supervisors (systemd, supervisord, shell wrappers) dropping env vars; Docker/Kubernetes manifests listing one env var but not the other; manually exporting the socket path but forgetting the token.

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

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

Appendix: source

Thrown at src/Aspire.Hosting.CodeGeneration.Python/PythonModuleBuilder.cs:1820

    /// </summary>
    public const string ConnectionHelperCode = """
        def _get_client(*, debug: bool, heartbeat_interval: int | None) -> AspireClient:
            '''
            Creates and connects to the Aspire AppHost.
            Reads connection info from environment variables set by `aspire run`.
            '''
            socket_path = os.environ.get('REMOTE_APP_HOST_SOCKET_PATH')
            if not socket_path:
                raise ValueError(
                    'REMOTE_APP_HOST_SOCKET_PATH environment variable not set. '
                    'Run this application using `aspire run`.'
                )

            client = AspireClient(socket_path, debug=debug, heartbeat_interval=heartbeat_interval)
            client.connect()
            auth_token = os.environ.get('ASPIRE_REMOTE_APPHOST_TOKEN')
            if not auth_token:
                raise ValueError(
                    'ASPIRE_REMOTE_APPHOST_TOKEN environment variable not set. '
                    'Run this application using `aspire run`.'
                )
            client.authenticate(auth_token)
            return client


        def create_builder(
            *,
            args: typing.Iterable[str] | None = None,
            project_directory: str | None = None,
            app_host_file_path: str | None = None,
            container_registry_override: str | None = None,
            disable_dashboard: bool | None = None,
            dashboard_application_name: str | None = None,
            allow_unsecured_transport: bool | None = None,
            enable_resource_logging: bool | None = None,
            options: CreateBuilderOptions | None = None,

View on GitHub (pinned to 25830f84bd)