java-native-access/jna · error · Win32Exception

Win32Exception(rc)

Error message

Win32Exception(rc)

What it means

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.

Source

Thrown at contrib/platform/src/com/sun/jna/platform/win32/Netapi32Util.java:123

        return getDCName(null, null);
    }

    /**
     * Returns the name of the primary domain controller (PDC).
     * @param serverName
     *     Specifies the DNS or NetBIOS name of the remote server on which the function is
     *     to execute.
     * @param domainName
     *     Specifies the name of the domain.
     * @return
     *  Name of the primary domain controller.
     */
    public static String getDCName(String serverName, String domainName) {
        PointerByReference bufptr = new PointerByReference();
        try {
            int rc = Netapi32.INSTANCE.NetGetDCName(serverName, domainName, bufptr);
            if (LMErr.NERR_Success != rc) {
                throw new Win32Exception(rc);
            }
            return bufptr.getValue().getWideString(0);
        } finally {
            if (W32Errors.ERROR_SUCCESS != Netapi32.INSTANCE.NetApiBufferFree(bufptr.getValue())) {
                throw new Win32Exception(Kernel32.INSTANCE.GetLastError());
            }
        }
    }

    /**
     * Return the domain/workgroup join status for a computer.
     * @return Join status.
     */
    public static int getJoinStatus() {
        return getJoinStatus(null);
    }

    /**

View on GitHub (pinned to d036ad9781)

Solutions

1. Catch Win32Exception and inspect getErrorCode(); for 2453 (NERR_DCNotFound) verify the domain name and DC reachability (nltest /dsgetdc:<domain>).
2. Pass null for serverName to run against the local machine, and pass null for domainName only if the machine is domain-joined.
3. Verify DNS resolution of the domain and that ports needed for DC location (UDP 389, DNS 53, SMB 445) are open.
4. Run under an account that can query the target domain; test with nltest or PowerShell Get-ADDomainController first.

Example fix

// before
String dc = Netapi32Util.getDCName(null, "MYDOMAIN");
// after
try {
    String dc = Netapi32Util.getDCName(null, "MYDOMAIN.local");
} catch (Win32Exception e) {
    if (e.getErrorCode() == 2453) { // NERR_DCNotFound
        // fall back to workgroup/local handling
    } else {
        throw e;
    }
}

// Pre-check domain reachability before calling
String domain = "MYDOMAIN.local";
boolean resolvable = java.net.InetAddress.getByName(domain) != null; // DNS check
if (!resolvable) throw new IllegalStateException("Domain not resolvable: " + domain);

try {
    String dc = Netapi32Util.getDCName(serverName, domainName);
} catch (Win32Exception e) {
    switch (e.getErrorCode()) {
        case 2453: /* NERR_DCNotFound: check domain name/DNS */ break;
        case 5:    /* ACCESS_DENIED: check credentials */ break;
        default: throw e;
    }
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Win32Exception(Kernel32.INSTANCE.GetLastError())
• LookupAccountNameW was expected to fail with ERROR_INSUFFICI
• Expected GetTokenInformation to fail with ERROR_INSUFFICIENT
• Failed to find privilege "{privilege}" - {GetLastError}
• Win32Exception from native GetLastError after GetPrivateProf

AI-assisted analysis of java-native-access/jna@d036ad9781 (2026-09-12). Data as JSON: /api/errors/201b54242392b7e2. Report an issue: GitHub.