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

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

This error is thrown by Java client code generated by the ATS Java code generator. After connecting to the AppHost socket, the generated `AspireClient.connect()` authenticates using the ASPIRE_REMOTE_APPHOST_TOKEN environment variable, which `aspire run` sets to a per-run token. If it is missing or empty, the client throws a RuntimeException rather than attempting an unauthenticated connection that would be rejected by the server anyway.

Solutions

  1. Run the application via `aspire run` so both the socket path and ASPIRE_REMOTE_APPHOST_TOKEN are set consistently for the current AppHost instance.
  2. If running manually, export ASPIRE_REMOTE_APPHOST_TOKEN with the current run's token value (it changes per run, so re-read it from the running AppHost) before starting the Java client.
  3. Ensure the client process shares the environment of the `aspire run` session (same user/session/container); tokens are per-run so stale exported values may also be rejected after re-connecting.
  4. Double-check the variable name spelling (ASPIRE_REMOTE_APPHOST_TOKEN) in your shell profile or launcher configuration.

Example fix

// before
export REMOTE_APP_HOST_SOCKET_PATH=/tmp/aspire/apphost.sock
java -jar target/app.jar   // RuntimeException: ASPIRE_REMOTE_APPHOST_TOKEN not set

// after
aspire run   // or: export ASPIRE_REMOTE_APPHOST_TOKEN=<current-run-token> before launching
Defensive patterns

Strategy: validation

Validate before calling

String token = System.getenv("ASPIRE_REMOTE_APPHOST_TOKEN");
if (token == null || token.isEmpty()) {
  throw new IllegalStateException("Missing ASPIRE_REMOTE_APPHOST_TOKEN - launch via 'aspire run'");
}

Try / catch

try {
  AspireClient client = AspireClient.connect();
} catch (RuntimeException e) {
  if (e.getMessage().contains("ASPIRE_REMOTE_APPHOST_TOKEN")) {
    // re-launch via aspire run or refresh the per-run token
  }
}

Prevention

When it happens

Trigger: Calling the generated `AspireClient.connect()` when the socket path exists (REMOTE_APP_HOST_SOCKET_PATH is set and the client connected) but ASPIRE_REMOTE_APPHOST_TOKEN is unset or empty.

Common situations: Manually exporting REMOTE_APP_HOST_SOCKET_PATH but forgetting the token; reusing an old shell session where the token from a previous `aspire run` was cleared; copying environment setup instructions partially; running the client in a different container/user session than the one `aspire run` configured.

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

Appendix: source

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

        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());");
        WriteLine("        }");
        WriteLine("        if (resolvedOptions.get(\"Args\") == null) {");
        // Python, TypeScript and Rust AppHosts read the process arguments themselves
        // (sys.argv[1:], process.argv.slice(2), std::env::args()), so a builder created without
        // arguments still observes "--operation publish". A JVM cannot do the same:
        // main(String[]) is the only place those arguments exist, and

View on GitHub (pinned to 25830f84bd)