{"record":{"id":"bae1820180fdd2b8","repo":"aeron-io/aeron","slug":"found-existing-archive-for-archiveid-archiveid","errorCode":null,"errorMessage":"found existing archive for archiveId=${archiveId}","messagePattern":"found existing archive for archiveId=(.+?)","errorType":"exception","errorClass":"ArchiveException","httpStatus":null,"severity":"error","filePath":"aeron-archive/src/main/java/io/aeron/archive/Archive.java","lineNumber":1359,"sourceCode":"                aeron = Aeron.connect(\n                    new Aeron.Context()\n                        .aeronDirectoryName(aeronDirectoryName)\n                        .epochClock(epochClock)\n                        .nanoClock(nanoClock)\n                        .errorHandler(errorHandler)\n                        .driverAgentInvoker(mediaDriverAgentInvoker)\n                        .useConductorAgentInvoker(true)\n                        .subscriberErrorHandler(RethrowingErrorHandler.INSTANCE)\n                        .awaitingIdleStrategy(YieldingIdleStrategy.INSTANCE)\n                        .clientLock(NoOpLock.INSTANCE)\n                        .clientName(clientName));\n\n                if (null == errorCounter)\n                {\n                    if (NULL_VALUE !=\n                        ArchiveCounters.find(aeron.countersReader(), ARCHIVE_ERROR_COUNT_TYPE_ID, archiveId))\n                    {\n                        throw new ArchiveException(\"found existing archive for archiveId=\" + archiveId);\n                    }\n                    errorCounter = ArchiveCounters.allocateErrorCounter(aeron, tempBuffer, archiveId);\n                }\n            }\n            else if (!aeron.context().useConductorAgentInvoker())\n            {\n                throw new ArchiveException(\n                    \"Aeron client instance must set Aeron.Context.useConductorInvoker(true)\");\n            }\n\n            if (!(aeron.context().subscriberErrorHandler() instanceof RethrowingErrorHandler))\n            {\n                throw new ArchiveException(\"Aeron client must use a RethrowingErrorHandler\");\n            }\n\n            Objects.requireNonNull(errorCounter, \"Error counter must be supplied if aeron client is\");\n\n            if (null == countedErrorHandler)","sourceCodeStart":1341,"sourceCodeEnd":1377,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-archive/src/main/java/io/aeron/archive/Archive.java#L1341-L1377","documentation":"While allocating the archive error counter, the archive found an existing Aeron counter with ARCHIVE_ERROR_COUNT_TYPE_ID already registered for the same archiveId. This means another Archive instance is already running with that identity against the same media driver, so startup fails with an ArchiveException to prevent two archives sharing one identity.","triggerScenarios":"Starting a second Archive process/context with the same archiveId while the first still holds its error counter on the driver; a crashed archive whose counters were not released (driver still up) followed by a restart reusing the archiveId; incorrectly reusing a fixed archiveId across multiple archive instances.","commonSituations":"Failover scripts restarting the archive while the old process is still connected; misconfigured clusters pointing several archive nodes at one driver with identical archiveId; leftover embedded archives in the same JVM (Aeron client not closed).","solutions":["Shut down the existing Archive process (or close its Aeron client) before restarting","Use a unique archiveId per Archive instance instead of a hardcoded one","Restart/recreate the media driver so stale counters are cleared if the previous owner is definitively dead","Check via ArchiveCounters.find / aeron counters whether an archive is already registered before starting"],"exampleFix":"// before\nctx.archiveId(42); // hardcoded, collides with running archive\n// after\nctx.archiveId(System.nanoTime()); // or omit to let it be generated\n// and ensure the previous archive is fully closed first","handlingStrategy":"try-catch","validationCode":"CountersReader counters = aeron.countersReader();\nif (NULL_VALUE != ArchiveCounters.find(counters, ArchiveCounters.ARCHIVE_ERROR_COUNT_TYPE_ID, archiveId)) {\n    throw new IllegalStateException(\"archive already running for archiveId=\" + archiveId);\n}","typeGuard":null,"tryCatchPattern":"try {\n    archive.start();\n} catch (ArchiveException e) {\n    if (e.getMessage().contains(\"found existing archive\")) {\n        // stop the other instance or choose a different archiveId, then retry\n    }\n}","preventionTips":["Ensure each Archive instance has a unique archiveId","Stop and fully close the previous archive (including its Aeron client) before restarting","Add health checks that detect an already-running archive before start scripts relaunch it"],"tags":["aeron-archive","duplicate-instance","archive-id","counters","startup"],"backgroundTag":"file-already-exists","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}