{"record":{"id":"390fd1d8aec1e787","repo":"apache/incubator-seata","slug":"no-available-mac-found","errorCode":null,"errorMessage":"no available mac found","messagePattern":"no available mac found","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"common/src/main/java/org/apache/seata/common/util/IdWorker.java","lineNumber":174,"sourceCode":"\n    /**\n     * use lowest 10 bit of available MAC as workerId\n     * @return workerId\n     * @throws Exception when there is no available mac found\n     */\n    private long generateWorkerIdBaseOnMac() throws Exception {\n        Enumeration<NetworkInterface> all = NetworkInterface.getNetworkInterfaces();\n        while (all.hasMoreElements()) {\n            NetworkInterface networkInterface = all.nextElement();\n            boolean isLoopback = networkInterface.isLoopback();\n            boolean isVirtual = networkInterface.isVirtual();\n            byte[] mac = networkInterface.getHardwareAddress();\n            if (isLoopback || isVirtual || mac == null) {\n                continue;\n            }\n            return ((mac[4] & 0B11) << 8) | (mac[5] & 0xFF);\n        }\n        throw new RuntimeException(\"no available mac found\");\n    }\n\n    /**\n     * randomly generate one as workerId\n     * @return workerId\n     */\n    private long generateRandomWorkerId() {\n        return new Random().nextInt(maxWorkerId + 1);\n    }\n}\n","sourceCodeStart":156,"sourceCodeEnd":185,"githubUrl":"https://github.com/apache/incubator-seata/blob/e01f97c6db397165050caa6764020410c2c8199a/common/src/main/java/org/apache/seata/common/util/IdWorker.java#L156-L185","documentation":"When IdWorker is given no explicit workerId, it derives one from the host's MAC address (generateWorkerIdBaseOnMac). It walks NetworkInterface.getNetworkInterfaces(), skipping loopback, virtual, and interfaces without a hardware address. If every interface is skipped (or there are none), it throws RuntimeException(\"no available mac found\").","triggerScenarios":"Running on a host or container with only lo (loopback), virtual interfaces (veth, docker0 without a MAC), or interfaces whose getHardwareAddress() returns null — common in minimal Docker images and some CI environments — while workerId is left null/auto.","commonSituations":"Slim/minimal Docker containers (no eth0), sandboxed CI runners, or hosts where Java SecurityManager permissions block network interface enumeration (which surfaces as the enclosing Exception).","solutions":["Supply an explicit in-range workerId (0-1023) instead of relying on MAC auto-generation","Ensure the container/host has a non-loopback, non-virtual network interface (e.g. run with a normal bridge network, not --network none)","Run with a JVM policy that permits NetworkInterface access"],"exampleFix":"// before\nIdWorker worker = new IdWorker(null); // auto -> may throw 'no available mac found' in containers\n\n// after\nIdWorker worker = new IdWorker(Integer.getInteger(\"worker.id\", 0));","handlingStrategy":"fallback","validationCode":"boolean hasMac = Collections.list(NetworkInterface.getNetworkInterfaces()).stream().anyMatch(ni -> { try { return !ni.isLoopback() && !ni.isVirtual() && ni.getHardwareAddress() != null; } catch (SocketException e) { return false; } });\nif (!hasMac) workerId = explicitOrRandomId;","typeGuard":null,"tryCatchPattern":"try { idWorker = new IdWorker(null); } catch (RuntimeException e) { idWorker = new IdWorker(configuredWorkerId); }","preventionTips":["Always set an explicit workerId in containerized deployments","Give containers a non-loopback network interface","Smoke-test ID generation in your base CI image"],"tags":["id-generation","docker","network-interface","environment"],"backgroundTag":null,"analyzedSha":"e01f97c6db397165050caa6764020410c2c8199a","analyzedAt":"2026-08-14T10:23:53.097Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}