{"record":{"id":"365e840ed362acc0","repo":"microsoft/aspire","slug":"aspire-remote-apphost-token-environment-variable-not-set-run","errorCode":null,"errorMessage":"ASPIRE_REMOTE_APPHOST_TOKEN environment variable not set. Run this application using `aspire run`.","messagePattern":"ASPIRE_REMOTE_APPHOST_TOKEN environment variable not set\\. Run this application using `aspire run`\\.","errorType":"exception","errorClass":"RuntimeException (in generated Java code)","httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting.CodeGeneration.Java/AtsJavaCodeGenerator.cs","lineNumber":2345,"sourceCode":"        WriteLine(\"// ============================================================================\");\n        WriteLine(\"// Connection Helpers\");\n        WriteLine(\"// ============================================================================\");\n        WriteLine();\n        WriteLine(\"/** Main entry point for Aspire SDK. */\");\n        WriteLine(\"public class Aspire {\");\n        WriteLine(\"    /** Connect to the AppHost server. */\");\n        WriteLine(\"    public static AspireClient connect() throws Exception {\");\n        WriteLine(\"        BaseRegistrations.ensureRegistered();\");\n        WriteLine(\"        AspireRegistrations.ensureRegistered();\");\n        WriteLine(\"        String socketPath = System.getenv(\\\"REMOTE_APP_HOST_SOCKET_PATH\\\");\");\n        WriteLine(\"        if (socketPath == null || socketPath.isEmpty()) {\");\n        WriteLine(\"            throw new RuntimeException(\\\"REMOTE_APP_HOST_SOCKET_PATH environment variable not set. Run this application using `aspire run`.\\\");\");\n        WriteLine(\"        }\");\n        WriteLine(\"        AspireClient client = new AspireClient(socketPath);\");\n        WriteLine(\"        client.connect();\");\n        WriteLine(\"        String authToken = System.getenv(\\\"ASPIRE_REMOTE_APPHOST_TOKEN\\\");\");\n        WriteLine(\"        if (authToken == null || authToken.isEmpty()) {\");\n        WriteLine(\"            throw new RuntimeException(\\\"ASPIRE_REMOTE_APPHOST_TOKEN environment variable not set. Run this application using `aspire run`.\\\");\");\n        WriteLine(\"        }\");\n        WriteLine(\"        client.authenticate(authToken);\");\n        WriteLine(\"        client.onDisconnect(() -> System.exit(1));\");\n        WriteLine(\"        return client;\");\n        WriteLine(\"    }\");\n        WriteLine();\n        WriteLine($\"    /** Create a new distributed application builder. */\");\n        WriteLine($\"    public static {builderClassName} createBuilder(CreateBuilderOptions options) throws Exception {{\");\n        WriteLine(\"        AspireClient client = connect();\");\n        WriteLine(\"        Map<String, Object> resolvedOptions = new HashMap<>();\");\n        WriteLine(\"        if (options != null) {\");\n        WriteLine(\"            resolvedOptions.putAll(options.toMap());\");\n        WriteLine(\"        }\");\n        WriteLine(\"        if (resolvedOptions.get(\\\"Args\\\") == null) {\");\n        // Python, TypeScript and Rust AppHosts read the process arguments themselves\n        // (sys.argv[1:], process.argv.slice(2), std::env::args()), so a builder created without\n        // arguments still observes \"--operation publish\". A JVM cannot do the same:\n        // main(String[]) is the only place those arguments exist, and","sourceCodeStart":2327,"sourceCodeEnd":2363,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting.CodeGeneration.Java/AtsJavaCodeGenerator.cs#L2327-L2363","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Run the application via `aspire run` so both the socket path and ASPIRE_REMOTE_APPHOST_TOKEN are set consistently for the current AppHost instance.","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.","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.","Double-check the variable name spelling (ASPIRE_REMOTE_APPHOST_TOKEN) in your shell profile or launcher configuration."],"exampleFix":"// before\nexport REMOTE_APP_HOST_SOCKET_PATH=/tmp/aspire/apphost.sock\njava -jar target/app.jar   // RuntimeException: ASPIRE_REMOTE_APPHOST_TOKEN not set\n\n// after\naspire run   // or: export ASPIRE_REMOTE_APPHOST_TOKEN=<current-run-token> before launching","handlingStrategy":"validation","validationCode":"String token = System.getenv(\"ASPIRE_REMOTE_APPHOST_TOKEN\");\nif (token == null || token.isEmpty()) {\n  throw new IllegalStateException(\"Missing ASPIRE_REMOTE_APPHOST_TOKEN - launch via 'aspire run'\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  AspireClient client = AspireClient.connect();\n} catch (RuntimeException e) {\n  if (e.getMessage().contains(\"ASPIRE_REMOTE_APPHOST_TOKEN\")) {\n    // re-launch via aspire run or refresh the per-run token\n  }\n}","preventionTips":["Remember tokens are per-run: re-export the token after every new `aspire run`.","Run the client in the same session/container as the AppHost so both env vars are present.","Validate both REMOTE_APP_HOST_SOCKET_PATH and ASPIRE_REMOTE_APPHOST_TOKEN before connecting."],"tags":["java","authentication","environment","token"],"backgroundTag":"missing-env-var","analyzedSha":"25830f84bd145686607ad00c057b3f84e2e51d43","analyzedAt":"2026-09-16T11:10:06.193Z","contentChangedAt":"2026-09-16T11:10:06.193Z","schemaVersion":2},"datasetVersion":"2026-09-21T04:17:39.646Z"}