{"record":{"id":"1e37f4f0769c0cf5","repo":"java-native-access/jna","slug":"ras32exception-err","errorCode":null,"errorMessage":"Ras32Exception(err)","messagePattern":"Ras32Exception\\(err\\)","errorType":"error_code","errorClass":"Ras32Exception","httpStatus":null,"severity":"error","filePath":"contrib/platform/src/com/sun/jna/platform/win32/Rasapi32Util.java","lineNumber":149,"sourceCode":"     * @return the descriptive text\n     */\n    public static String getRasConnectionStatusText(int connStatus) {\n        if (!CONNECTION_STATE_TEXT.containsKey(connStatus)) return Integer.toString(connStatus);\n        return (String)CONNECTION_STATE_TEXT.get(connStatus);\n    }\n\n    /**\n     * Return a RAS connection by name\n     * @param connName the connection name\n     * @return the RAS connection structure\n     * @throws Ras32Exception errors\n     */\n    public static HANDLE getRasConnection(String connName) throws Ras32Exception {\n        // size the array needed\n        IntByReference lpcb  = new IntByReference(0);\n        IntByReference lpcConnections  = new IntByReference();\n        int err = Rasapi32.INSTANCE.RasEnumConnections(null, lpcb, lpcConnections);\n        if (err != WinError.ERROR_SUCCESS && err != WinRas.ERROR_BUFFER_TOO_SMALL) throw new Ras32Exception(err);\n        if (lpcb.getValue() == 0) return null;\n\n        // get the connections\n        RASCONN[] connections = new RASCONN[lpcConnections.getValue()];\n        for (int i = 0; i < lpcConnections.getValue(); i++) connections[i] = new RASCONN();\n        lpcb  = new IntByReference(connections[0].dwSize * lpcConnections.getValue());\n        err = Rasapi32.INSTANCE.RasEnumConnections(connections, lpcb, lpcConnections);\n        if (err != WinError.ERROR_SUCCESS) throw new Ras32Exception(err);\n\n        // find connection\n        for (int i = 0; i < lpcConnections.getValue(); i++) {\n            if (new String(connections[i].szEntryName).equals(connName)) return connections[i].hrasconn;\n        }\n        return null;\n    }\n\n    /**\n     * Hangup a connection by name","sourceCodeStart":131,"sourceCodeEnd":167,"githubUrl":"https://github.com/java-native-access/jna/blob/d036ad9781adad4b66693e8fa7098e4ac665e0a3/contrib/platform/src/com/sun/jna/platform/win32/Rasapi32Util.java#L131-L167","documentation":"Rasapi32Util.getRasConnection looks up an active RAS connection by name using RasEnumConnections. Native RAS error codes other than success/ERROR_BUFFER_TOO_SMALL (on the sizing call) or ERROR_SUCCESS (on the data call) are wrapped in Ras32Exception carrying the RAS error code.","triggerScenarios":"RasEnumConnections failing — e.g. RAS not installed/available on the machine, insufficient permissions to read connection data, or the data-call phase returning a RAS error code after the sizing call succeeded.","commonSituations":"Calling RAS APIs on machines without dial-up/VPN (RasMan) service enabled; RasMan service stopped; searching for a connection name that simply does not exist (the method then returns null rather than throwing); restricted environments blocking RAS API access.","solutions":["Check the error code inside Ras32Exception against WinRas constants (e.g. ERROR RasMan issues)","Ensure the Remote Access Connection Manager (RasMan) Windows service is running","Verify RAS/VPN support exists on the target machine","Handle the null return (connection name not found) separately from the exception path"],"exampleFix":"// before\nHANDLE h = Rasapi32Util.getRasConnection(connName);\n// after\nHANDLE h;\ntry {\n    h = Rasapi32Util.getRasConnection(connName);\n} catch (Ras32Exception e) {\n    LOG.warn(\"RAS lookup failed with code \" + e.getErrorCode());\n    h = null;\n}","handlingStrategy":"try-catch","validationCode":"if (connName == null || connName.isEmpty()) throw new IllegalArgumentException(\"connection name required\");","typeGuard":null,"tryCatchPattern":"try { return Rasapi32Util.getRasConnection(connName); } catch (Ras32Exception e) { LOG.warn(\"RAS error \" + e.getErrorCode()); return null; }","preventionTips":["Ensure the RasMan service is running on machines using RAS lookups","Distinguish null (connection not found) from Ras32Exception (API failure)","Check RAS error codes against WinRas constants for precise diagnostics"],"tags":["windows","ras","vpn","jni"],"backgroundTag":"api-error-response","analyzedSha":"d036ad9781adad4b66693e8fa7098e4ac665e0a3","analyzedAt":"2026-09-12T06:50:59.239Z","contentChangedAt":"2026-09-12T06:50:59.239Z","schemaVersion":2},"datasetVersion":"2026-09-19T12:17:13.211Z"}