{"record":{"id":"201b54242392b7e2","repo":"java-native-access/jna","slug":"win32exception-rc","errorCode":null,"errorMessage":"Win32Exception(rc)","messagePattern":"Win32Exception\\(rc\\)","errorType":"error_code","errorClass":"Win32Exception","httpStatus":null,"severity":"error","filePath":"contrib/platform/src/com/sun/jna/platform/win32/Netapi32Util.java","lineNumber":123,"sourceCode":"        return getDCName(null, null);\n    }\n\n    /**\n     * Returns the name of the primary domain controller (PDC).\n     * @param serverName\n     *     Specifies the DNS or NetBIOS name of the remote server on which the function is\n     *     to execute.\n     * @param domainName\n     *     Specifies the name of the domain.\n     * @return\n     *  Name of the primary domain controller.\n     */\n    public static String getDCName(String serverName, String domainName) {\n        PointerByReference bufptr = new PointerByReference();\n        try {\n            int rc = Netapi32.INSTANCE.NetGetDCName(serverName, domainName, bufptr);\n            if (LMErr.NERR_Success != rc) {\n                throw new Win32Exception(rc);\n            }\n            return bufptr.getValue().getWideString(0);\n        } finally {\n            if (W32Errors.ERROR_SUCCESS != Netapi32.INSTANCE.NetApiBufferFree(bufptr.getValue())) {\n                throw new Win32Exception(Kernel32.INSTANCE.GetLastError());\n            }\n        }\n    }\n\n    /**\n     * Return the domain/workgroup join status for a computer.\n     * @return Join status.\n     */\n    public static int getJoinStatus() {\n        return getJoinStatus(null);\n    }\n\n    /**","sourceCodeStart":105,"sourceCodeEnd":141,"githubUrl":"https://github.com/java-native-access/jna/blob/d036ad9781adad4b66693e8fa7098e4ac665e0a3/contrib/platform/src/com/sun/jna/platform/win32/Netapi32Util.java#L105-L141","documentation":"getDCName calls NetGetDCName to find the primary domain controller name. If the native call returns any code other than NERR_Success, the library wraps that Win32 error code in a Win32Exception and throws it. This is the library's standard way of surfacing native Netapi32 failures to Java callers.","triggerScenarios":"NetGetDCName(serverName, domainName) returns a non-success rc — e.g. NERR_DCNotFound (2453) when no domain controller is reachable for the given domain, ERROR_INVALID_NAME when server/domain name is malformed, or access-denied codes when the caller lacks rights.","commonSituations":"Querying a domain controller from a machine not joined to the domain; typos in the domain/workgroup name; firewall or DNS blocking DC discovery; calling with a null domain on a workgroup machine; network offline or AD unreachable.","solutions":["Catch Win32Exception and inspect getErrorCode(); for 2453 (NERR_DCNotFound) verify the domain name and DC reachability (nltest /dsgetdc:<domain>).","Pass null for serverName to run against the local machine, and pass null for domainName only if the machine is domain-joined.","Verify DNS resolution of the domain and that ports needed for DC location (UDP 389, DNS 53, SMB 445) are open.","Run under an account that can query the target domain; test with nltest or PowerShell Get-ADDomainController first."],"exampleFix":"// before\nString dc = Netapi32Util.getDCName(null, \"MYDOMAIN\");\n// after\ntry {\n    String dc = Netapi32Util.getDCName(null, \"MYDOMAIN.local\");\n} catch (Win32Exception e) {\n    if (e.getErrorCode() == 2453) { // NERR_DCNotFound\n        // fall back to workgroup/local handling\n    } else {\n        throw e;\n    }\n}","handlingStrategy":"try-catch","validationCode":"// Pre-check domain reachability before calling\nString domain = \"MYDOMAIN.local\";\nboolean resolvable = java.net.InetAddress.getByName(domain) != null; // DNS check\nif (!resolvable) throw new IllegalStateException(\"Domain not resolvable: \" + domain);","typeGuard":null,"tryCatchPattern":"try {\n    String dc = Netapi32Util.getDCName(serverName, domainName);\n} catch (Win32Exception e) {\n    switch (e.getErrorCode()) {\n        case 2453: /* NERR_DCNotFound: check domain name/DNS */ break;\n        case 5:    /* ACCESS_DENIED: check credentials */ break;\n        default: throw e;\n    }\n}","preventionTips":["Verify the domain is DNS-resolvable and reachable (nltest /dsgetdc:<domain>) before calling.","Pass null serverName to target the local machine unless a specific server is required.","Confirm the machine is domain-joined (Netapi32Util.getJoinStatus(null)) before requesting a DC.","Catch Win32Exception and branch on getErrorCode() rather than letting it propagate."],"tags":["win32","jna","active-directory","native"],"backgroundTag":"win32-api-error","analyzedSha":"d036ad9781adad4b66693e8fa7098e4ac665e0a3","analyzedAt":"2026-09-12T06:50:59.239Z","contentChangedAt":"2026-09-12T06:50:59.239Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}