{"record":{"id":"35bb10bf6b105979","repo":"perwendel/spark","slug":"server-has-not-been-properly-initialized","errorCode":null,"errorMessage":"Server has not been properly initialized","messagePattern":"Server has not been properly initialized","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"src/main/java/spark/Service.java","lineNumber":492,"sourceCode":"     */\n    public synchronized void notFound(Route route) {\n        CustomErrorPages.add(404, route);\n    }\n\n    /**\n     * Maps 500 internal server errors to the provided route.\n     */\n    public synchronized void internalServerError(Route route) {\n        CustomErrorPages.add(500, route);\n    }\n\n    /**\n     * Waits for the spark server to be initialized.\n     * If it's already initialized will return immediately\n     */\n    public void awaitInitialization() {\n        if (!initialized) {\n    \t        throw new IllegalStateException(\"Server has not been properly initialized\");\n        }\n\n        try {\n            initLatch.await();\n        } catch (InterruptedException e) {\n            LOG.info(\"Interrupted by another thread\");\n            Thread.currentThread().interrupt();\n        }\n    }\n\n    private void throwBeforeRouteMappingException() {\n        throw new IllegalStateException(\n                \"This must be done before route mapping has begun\");\n    }\n\n    private boolean hasMultipleHandlers() {\n        return webSocketHandlers != null;\n    }","sourceCodeStart":474,"sourceCodeEnd":510,"githubUrl":"https://github.com/perwendel/spark/blob/1973e402f5d4c1442ad34a1d38ed0758079f7773/src/main/java/spark/Service.java#L474-L510","documentation":"Service.awaitInitialization() blocks until the embedded server's init latch is released, letting users wait for server startup before proceeding (e.g. in tests). If the Service was never initialized — no route mapping occurred, so 'initialized' is false — waiting would block forever, so Spark throws IllegalStateException instead.","triggerScenarios":"Calling Spark.awaitInitialization() (or Service.awaitInitialization()) before any route mapping call has marked the service initialized, e.g. calling it at the top of main() before mapping any routes, or on a Service instance that never had routes registered.","commonSituations":"Test setup code calling awaitInitialization() before defining routes; copy-pasted boilerplate in the wrong order; calling awaitInitialization in a wrapper library that never maps routes itself.","solutions":["Map at least one route (get/post/staticFiles etc.) before calling awaitInitialization().","Call init() (or ensure routes are mapped) and only then awaitInitialization().","If the server may not be started, check your own bootstrap state before relying on awaitInitialization."],"exampleFix":"// before\nSpark.awaitInitialization(); // too early\nSpark.get(\"/hello\", (req, res) -> \"hi\");\n// after\nSpark.get(\"/hello\", (req, res) -> \"hi\");\nSpark.init();\nSpark.awaitInitialization();","handlingStrategy":"try-catch","validationCode":"if (routesMapped) { // your own bootstrap flag\n    Spark.awaitInitialization();\n}","typeGuard":null,"tryCatchPattern":"try {\n    Spark.awaitInitialization();\n} catch (IllegalStateException e) {\n    LOG.warn(\"Server was never initialized; skipping wait\");\n}","preventionTips":["Always map at least one route before awaiting initialization.","In tests, call init() before awaitInitialization().","Centralize startup order: map routes -> init -> awaitInitialization."],"tags":["java","illegal-state","server-lifecycle"],"backgroundTag":"invalid-state-transition","analyzedSha":"1973e402f5d4c1442ad34a1d38ed0758079f7773","analyzedAt":"2026-09-10T14:38:22.866Z","contentChangedAt":"2026-09-10T14:38:22.866Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}