microsoft/aspire · error · ValueError

REMOTE_APP_HOST_SOCKET_PATH environment variable not set…

Error message

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

What it means

The Python remote client reads its connection endpoint from the REMOTE_APP_HOST_SOCKET_PATH environment variable, which `aspire run` sets for the processes it launches. When absent it raises ValueError telling the developer to launch via `aspire run`.

Solutions

  1. Start the application with `aspire run` so the AppHost injects REMOTE_APP_HOST_SOCKET_PATH.
  2. If running under a debugger, configure the launch profile/task to use `aspire run` as the launch command.
  3. Manually set REMOTE_APP_HOST_SOCKET_PATH to the AppHost socket path when launching out-of-band.
  4. Ensure the parent process that spawns the app propagates its environment (no stripped env).

Example fix

# before
python app.py
# after
aspire run
Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

def can_connect() -> bool:
    return bool(os.environ.get("REMOTE_APP_HOST_SOCKET_PATH"))

Try / catch

try:
    client = connect_aspire()
except ValueError:
    raise SystemExit("start the app with `aspire run` instead of running it directly")

Prevention

When it happens

Trigger: Running the Python app directly (`python app.py`, IDE run button, debugger, plain container) instead of through `aspire run`, or spawning it from a context that did not inherit the env var.

Common situations: Debugging in VS Code/PyCharm which launches the interpreter directly; running inside Docker without passing the env var; CI jobs invoking the script without the Aspire CLI wrapper.

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/abb45982362e95ee. Report an issue: GitHub.

Appendix: source

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

            def run(self, *, timeout: int | None = None) -> None:
                '''Builds and runs the distributed application.'''
                app = self.build()
                app.run(timeout=timeout)

        """;

    /// <summary>
    /// Connection helper code for creating the Aspire client and builder.
    /// </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(
            *,

View on GitHub (pinned to 25830f84bd)