perwendel/spark · error · IllegalStateException

This must be done before route mapping has begun

Error message

This must be done before route mapping has begun

What it means

throwBeforeRouteMappingException is Service's shared helper that raises IllegalStateException('This must be done before route mapping has begun'). Server configuration methods — ipAddress, port(int), threadPool, secure, staticFileLocation, embeddedServerIdentifier — must run before Spark initializes its embedded server, which happens as soon as route mapping begins. Calling them afterwards is a lifecycle-ordering violation, so the server refuses.

Solutions

1. Move all Spark.port/ipAddress/threadPool/secure/staticFileLocation calls to the very beginning of the bootstrap, before any route registration.
2. Restructure bootstrap into a single ordered init method: configure server first, then map routes, then init().
3. In modular apps, split 'server config' and 'route registration' phases with enforced ordering.

Example fix

// before
Spark.get("/hello", (req, res) -> "hi");
Spark.port(8080); // IllegalStateException
// after
Spark.port(8080);
Spark.get("/hello", (req, res) -> "hi");

// enforce ordering in your bootstrap
configureServer(Spark.port(8080));
mapRoutes();

try {
    Spark.staticFileLocation("/public");
} catch (IllegalStateException e) {
    throw new IllegalStateException("staticFileLocation must be called before route mapping; fix bootstrap order", e);
}

When it happens

Trigger: Calling any of ipAddress(...), port(...), threadPool(...), secure(...), staticFileLocation(...), or embeddedServerIdentifier(...) after at least one route-mapping call (get/post/put/staticFiles...) has initialized the service.

Common situations: Configuration split across classes where routes are registered before settings; conditional config applied late; setting the IP/port in a request handler or framework callback that runs after boot.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• This must be done after route mapping has begun
• Server has not been properly initialized
• HttpServletRequest cannot be null.
• Must provide a keystore file to run secured
• WebSockets are only supported in the embedded server

AI-assisted analysis of perwendel/spark@1973e402f5 (2026-09-10). Data as JSON: /api/errors/e6a0047635ca3ef3. Report an issue: GitHub.

Appendix: source

Thrown at src/main/java/spark/Service.java:504

    /**
     * Waits for the spark server to be initialized.
     * If it's already initialized will return immediately
     */
    public void awaitInitialization() {
        if (!initialized) {
    	        throw new IllegalStateException("Server has not been properly initialized");
        }

        try {
            initLatch.await();
        } catch (InterruptedException e) {
            LOG.info("Interrupted by another thread");
            Thread.currentThread().interrupt();
        }
    }

    private void throwBeforeRouteMappingException() {
        throw new IllegalStateException(
                "This must be done before route mapping has begun");
    }

    private boolean hasMultipleHandlers() {
        return webSocketHandlers != null;
    }


    /**
     * Stops the Spark server and clears all routes.
     */
    public synchronized void stop() {
    	if (!initialized) {
    		return;
    	}
        initiateStop();
    }

View on GitHub (pinned to 1973e402f5)