perwendel/spark · error · RuntimeException

No embedded server matching the identifier

Error message

No embedded server matching the identifier

What it means

EmbeddedServers.create() selects an EmbeddedServerFactory from a registry keyed by an EmbeddedServerIdentifier. If the identifier is not registered (only Jetty is registered by default; others must be added via EmbeddedServers.add), there is no factory to build the server and Spark throws RuntimeException('No embedded server matching the identifier').

Solutions

1. Register the factory before server creation: EmbeddedServers.add(myIdentifier, myFactory) early in bootstrap.
2. If you intended the default, don't set a custom embeddedServerIdentifier — omit it so Spark uses Jetty.
3. Verify the identifier value matches the one used in EmbeddedServers.add exactly.
4. Only use Service.embeddedServerIdentifier() before route mapping in embedded-server mode.

Example fix

// before
Spark.embeddedServerIdentifier("my-server"); // no factory registered
// after
EmbeddedServers.add(() -> "my-server", (r, s, e, m) -> new MyEmbeddedServer(r, s));
Spark.embeddedServerIdentifier("my-server");

// ensure registration before create/use
EmbeddedServers.add(myIdentifier, myFactory);
Spark.embeddedServerIdentifier(myIdentifier);

try {
    EmbeddedServers.create(identifier, routeMatcher, staticFiles, exceptionMapper, multipleHandlers);
} catch (RuntimeException e) {
    if (e.getMessage().contains("No embedded server matching")) {
        EmbeddedServers.add(identifier, defaultFactory);
        // retry create
    } else { throw e; }
}

When it happens

Trigger: Calling EmbeddedServers.create(identifier, ...) with an identifier never added via EmbeddedServers.add(), or configuring Service.embeddedServerIdentifier(...) with a custom identifier without registering a matching factory first.

Common situations: Custom identifier set via Spark.embeddedServerIdentifier(MyServer.ID) but the EmbeddedServers.add(...) registration call was removed, never executed, or runs after server creation; typos in the identifier.

Understand the failure class

Background: "missing required config value" errors: why libraries refuse to start when a configuration key is empty, unset, or blank — this error's family across 48 libraries.

Related errors

• ' ' doesn't support
• HttpServletRequest cannot be null.
• This must be done after route mapping has begun
• 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/0e1ab386714e0a1c. Report an issue: GitHub.

Appendix: source

Thrown at src/main/java/spark/embeddedserver/EmbeddedServers.java:82

     *
     * @param identifier               the identifier
     * @param routeMatcher             the route matcher
     * @param staticFilesConfiguration the static files configuration object
     * @param multipleHandlers         true if other handlers exist
     * @return the created EmbeddedServer object
     */
    public static EmbeddedServer create(Object identifier,
                                        Routes routeMatcher,
                                        ExceptionMapper exceptionMapper,
                                        StaticFilesConfiguration staticFilesConfiguration,
                                        boolean multipleHandlers) {

        EmbeddedServerFactory factory = factories.get(identifier);

        if (factory != null) {
            return factory.create(routeMatcher, staticFilesConfiguration, exceptionMapper, multipleHandlers);
        } else {
            throw new RuntimeException("No embedded server matching the identifier");
        }
    }

    /**
     * Adds an Embedded server factory for the provided identifier.
     *
     * @param identifier the identifier
     * @param factory    the factory
     */
    public static void add(Object identifier, EmbeddedServerFactory factory) {
        factories.put(identifier, factory);
    }

}

View on GitHub (pinned to 1973e402f5)