{"record":{"id":"f22d2840f099c122","repo":"microsoft/aspire","slug":"remote-app-host-socket-path-environment-variable-not-set-run","errorCode":null,"errorMessage":"REMOTE_APP_HOST_SOCKET_PATH environment variable not set. Run this application using `aspire run`.","messagePattern":"REMOTE_APP_HOST_SOCKET_PATH 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":2339,"sourceCode":"    private void GenerateConnectionHelpers()\n    {\n        var builderClassName = _classNames.TryGetValue(AtsConstants.BuilderTypeId, out var name)\n            ? name\n            : \"DistributedApplicationBuilder\";\n\n        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());\");","sourceCodeStart":2321,"sourceCodeEnd":2357,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting.CodeGeneration.Java/AtsJavaCodeGenerator.cs#L2321-L2357","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\ncd app && java -jar target/app.jar   // RuntimeException: REMOTE_APP_HOST_SOCKET_PATH not set\n\n// after\naspire run   // launches the app with the socket path and token injected","handlingStrategy":"validation","validationCode":"if (!process.env.REMOTE_APP_HOST_SOCKET_PATH /* Java: System.getenv(\"REMOTE_APP_HOST_SOCKET_PATH\") */) {\n  throw new Error(\"Not launched by 'aspire run': REMOTE_APP_HOST_SOCKET_PATH is missing\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  AspireClient client = AspireClient.connect();\n} catch (RuntimeException e) {\n  if (e.getMessage().contains(\"REMOTE_APP_HOST_SOCKET_PATH\")) {\n    // fall back to direct run instructions or exit with a clear message\n  }\n}","preventionTips":["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."],"tags":["java","environment","apphost","code-generation"],"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"}