microsoft/aspire · error · Error

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

This error is thrown by the TypeScript client code generated by the ATS TypeScript code generator. The generated `connect()` function reads REMOTE_APP_HOST_SOCKET_PATH from process.env to find the AppHost's Unix domain socket, because that path is only provided by `aspire run`. If the variable is unset or empty, the function throws an Error immediately rather than failing with an obscure socket connection error later.

Solutions

Run the application with `aspire run`, which sets REMOTE_APP_HOST_SOCKET_PATH and the auth token automatically.
For manual runs, export REMOTE_APP_HOST_SOCKET_PATH to the current AppHost socket path before starting Node (get the value from the running `aspire run` session).
In containers/CI, pass the variable through (e.g. docker run -e REMOTE_APP_HOST_SOCKET_PATH=... -v <socket>:/path/to/socket).
Check for dotenv or process-env sanitization in your app that may be wiping the injected environment variables.

Example fix

// before
node dist/index.js   // Error: REMOTE_APP_HOST_SOCKET_PATH not set

// after
aspire run   // or: REMOTE_APP_HOST_SOCKET_PATH=/tmp/aspire/apphost.sock node dist/index.js

Defensive patterns

Strategy: validation

Validate before calling

if (!process.env.REMOTE_APP_HOST_SOCKET_PATH) {
  console.error("Launch via 'aspire run' or set REMOTE_APP_HOST_SOCKET_PATH");
  process.exit(1);
}

Type guard

function hasSocketPath(env) { return typeof env.REMOTE_APP_HOST_SOCKET_PATH === 'string' && env.REMOTE_APP_HOST_SOCKET_PATH.length > 0; }

Try / catch

try {
  const client = await connect();
} catch (err) {
  if (String(err.message).includes('REMOTE_APP_HOST_SOCKET_PATH')) {
    // print launch instructions or exit gracefully
  }
}

Prevention

Launch generated apps via `aspire run`, not node/npm/IDE runners.
Pass the env var explicitly into containers (-e) and CI jobs.
Guard against dotenv configs overwriting/clearing injected env vars.

When it happens

Trigger: Calling the generated `connect()` (typically from the generated app's startup code) in a Node process where process.env.REMOTE_APP_HOST_SOCKET_PATH is undefined or an empty string.

Common situations: Starting the generated TypeScript app with `node dist/index.js`, npm, or an IDE debugger instead of `aspire run`; running inside Docker/CI without exporting the variable; using a terminal not launched through the AppHost so the connection environment was never injected.

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

Appendix: source

Thrown at src/Aspire.Hosting.CodeGeneration.TypeScript/AtsTypeScriptCodeGenerator.cs:1942

    }

    private void GenerateConnectionHelper()
    {
        var builderHandle = TypeScriptApiProjector.GetHandleTypeName(AtsConstants.BuilderTypeId);

        WriteLine($$"""
            // ============================================================================
            // Connection Helper
            // ============================================================================

            /**
             * Creates and connects to the Aspire AppHost.
             * Reads connection info from environment variables set by `aspire run`.
             */
            export async function connect(): Promise<AspireClientRpc> {
                const socketPath = process.env.REMOTE_APP_HOST_SOCKET_PATH;
                if (!socketPath) {
                    throw new Error(
                        'REMOTE_APP_HOST_SOCKET_PATH environment variable not set. ' +
                        'Run this application using `aspire run`.'
                    );
                }

                const client = new AspireClient(socketPath);
                await client.connect();

                // Exit the process if the server connection is lost
                client.onDisconnect(() => {
                    console.error('Connection to AppHost lost. Exiting...');
                    process.exit(1);
                });

                return client;
            }

            /**

View on GitHub (pinned to 25830f84bd)