microsoft/aspire · error · RuntimeException (in generated Java code)

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 Java client code generated by the ATS Java code generator. The generated `AspireClient.connect()` method requires the REMOTE_APP_HOST_SOCKET_PATH environment variable to locate the AppHost server's Unix domain socket. When the generated app is launched outside of `aspire run` (which injects these variables), the socket path is missing and the code throws a RuntimeException instead of failing later with an opaque connection error.

Solutions

Run the application through `aspire run` so the AppHost sets REMOTE_APP_HOST_SOCKET_PATH (and ASPIRE_REMOTE_APPHOST_TOKEN) automatically.
If you must run it manually, start the AppHost with `aspire run`, then copy the REMOTE_APP_HOST_SOCKET_PATH value it prints/exports into your process environment (e.g. export REMOTE_APP_HOST_SOCKET_PATH=/path/to/apphost.sock).
When running in CI or a container, mount/export the AppHost socket path and the auth token into the client process environment before starting the Java app.
Verify with `echo $REMOTE_APP_HOST_SOCKET_PATH` (or the Java equivalent System.getenv) that the variable is visible to the process actually running the client.

Example fix

// before
cd app && java -jar target/app.jar   // RuntimeException: REMOTE_APP_HOST_SOCKET_PATH not set

// after
aspire run   // launches the app with the socket path and token injected

Defensive patterns

Strategy: validation

Validate before calling

if (!process.env.REMOTE_APP_HOST_SOCKET_PATH /* Java: System.getenv("REMOTE_APP_HOST_SOCKET_PATH") */) {
  throw new Error("Not launched by 'aspire run': REMOTE_APP_HOST_SOCKET_PATH is missing");
}

Try / catch

try {
  AspireClient client = AspireClient.connect();
} catch (RuntimeException e) {
  if (e.getMessage().contains("REMOTE_APP_HOST_SOCKET_PATH")) {
    // fall back to direct run instructions or exit with a clear message
  }
}

Prevention

Always launch generated client apps through `aspire run`.
In CI, explicitly propagate the AppHost connection environment variables into the job/container.
Check for the required env vars at startup and fail fast with a clear message.

When it happens

Trigger: Calling the generated static method `AspireClient.connect()` (or running the generated Java app's main entry point) when the `REMOTE_APP_HOST_SOCKET_PATH` environment variable is unset or empty.

Common situations: Running the generated Java client directly with `java -jar` or from an IDE instead of via `aspire run`; running it inside a container or CI job where the AppHost environment was not propagated; a shell/terminal that was not started by the AppHost so `aspire run` never exported the variable.

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

Appendix: source

Thrown at src/Aspire.Hosting.CodeGeneration.Java/AtsJavaCodeGenerator.cs:2339

    private void GenerateConnectionHelpers()
    {
        var builderClassName = _classNames.TryGetValue(AtsConstants.BuilderTypeId, out var name)
            ? name
            : "DistributedApplicationBuilder";

        WriteLine("// ============================================================================");
        WriteLine("// Connection Helpers");
        WriteLine("// ============================================================================");
        WriteLine();
        WriteLine("/** Main entry point for Aspire SDK. */");
        WriteLine("public class Aspire {");
        WriteLine("    /** Connect to the AppHost server. */");
        WriteLine("    public static AspireClient connect() throws Exception {");
        WriteLine("        BaseRegistrations.ensureRegistered();");
        WriteLine("        AspireRegistrations.ensureRegistered();");
        WriteLine("        String socketPath = System.getenv(\"REMOTE_APP_HOST_SOCKET_PATH\");");
        WriteLine("        if (socketPath == null || socketPath.isEmpty()) {");
        WriteLine("            throw new RuntimeException(\"REMOTE_APP_HOST_SOCKET_PATH environment variable not set. Run this application using `aspire run`.\");");
        WriteLine("        }");
        WriteLine("        AspireClient client = new AspireClient(socketPath);");
        WriteLine("        client.connect();");
        WriteLine("        String authToken = System.getenv(\"ASPIRE_REMOTE_APPHOST_TOKEN\");");
        WriteLine("        if (authToken == null || authToken.isEmpty()) {");
        WriteLine("            throw new RuntimeException(\"ASPIRE_REMOTE_APPHOST_TOKEN environment variable not set. Run this application using `aspire run`.\");");
        WriteLine("        }");
        WriteLine("        client.authenticate(authToken);");
        WriteLine("        client.onDisconnect(() -> System.exit(1));");
        WriteLine("        return client;");
        WriteLine("    }");
        WriteLine();
        WriteLine($"    /** Create a new distributed application builder. */");
        WriteLine($"    public static {builderClassName} createBuilder(CreateBuilderOptions options) throws Exception {{");
        WriteLine("        AspireClient client = connect();");
        WriteLine("        Map<String, Object> resolvedOptions = new HashMap<>();");
        WriteLine("        if (options != null) {");
        WriteLine("            resolvedOptions.putAll(options.toMap());");

View on GitHub (pinned to 25830f84bd)