Elasticsearch UnknownServiceException: Unknown service - Common Causes & Fixes

java.net.UnknownServiceException is a JDK exception (or an AWS SDK exception of similar name) raised when client code tries to open a URL with a protocol or service the URL handler does not understand. With Elasticsearch and OpenSearch, you most often see it when client code passes a malformed URL (http+es://, localhost:9200 without scheme) or when an AWS SDK call is misconfigured for the AWS-hosted OpenSearch Service signing region. The request never leaves the client.

What This Error Means

UnknownServiceException originates client-side, not in Elasticsearch. The JDK or AWS SDK cannot resolve the URL's scheme/service. The cluster itself is unaffected and may be fully healthy.

The common patterns are: a connection string with a custom scheme that no URL handler is registered for; a missing https:// prefix in code that builds a URL; or an AWS Signature Version 4 signer configured for the wrong service name (es vs aoss for OpenSearch Serverless).

Common Causes

1. URL string missing scheme (localhost:9200 instead of http://localhost:9200). How to confirm: stack trace originates in java.net.URL and references URLStreamHandler.
2. Custom URI scheme used in code (e.g., elasticsearch://). How to confirm: client config passes a scheme not registered with the JVM.
3. AWS SDK Signer service name mismatch for AWS-hosted OpenSearch (es for managed clusters, aoss for Serverless). How to confirm: stack trace includes software.amazon.awssdk.* and the failing region/service combination.
4. Outdated AWS SDK without OpenSearch Serverless support. How to confirm: AWS SDK version older than 2.20 (Java v2) lacks aoss signing support.
5. HTTP-vs-HTTPS mismatch after enabling security. How to confirm: cluster moved to HTTPS but client still uses http://; some libraries surface this as UnknownServiceException rather than a TLS error.

How to Fix UnknownServiceException

1. Confirm the URL has a valid scheme (http or https):

   String url = "https://es.example.com:9200"; // not "es.example.com:9200"
   

2. For AWS-hosted OpenSearch Service, configure the AWS request signer with the correct service name:

   // Managed cluster
   AwsSdk2Transport transport = new AwsSdk2Transport(
       SdkAsyncHttpClient client, "search-mydomain-...es.amazonaws.com",
       "es", Region.US_EAST_1, AwsSdk2TransportOptions.builder().build());
   

   For Serverless, use "aoss".

3. Upgrade AWS SDK to a version supporting OpenSearch Serverless if applicable - 2.20.0+ for the Java v2 SDK.

4. For HTTPS-required clusters, update the client URL and ensure the truststore includes the cluster's CA:

   curl -k https://<es>:9200/   # quick check
   

5. Inspect the full stack trace. Frames in software.amazon.awssdk.* point at AWS SDK signing; frames in java.net.URL point at scheme handling.

6. Replace custom URI schemes with HTTP(S). Some legacy Elastic Cloud connection strings use proprietary forms - use the URL+API key pattern instead.

Resolve UnknownServiceException Automatically with Pulse

Pulse is an AI DBA for Elasticsearch and OpenSearch. When java.net.UnknownServiceException (or its AWS SDK equivalent) blocks a client from reaching the cluster, Pulse:

• Reads the stack trace's top non-JDK frame to distinguish a URL handler issue (java.net.URL), an AWS SDK signing problem (software.amazon.awssdk.*), or a library-internal scheme registration; correlates with the client's connection string, AWS SDK version, and the cluster's actual scheme via GET / (distribution: opensearch)
• Identifies which of the five causes applies: URL missing the http:///https:// scheme, custom URI scheme not registered with the JVM, AWS Signature V4 service name mismatch (es for managed vs aoss for OpenSearch Serverless), AWS SDK older than 2.20 with no aoss support, or HTTP-vs-HTTPS mismatch after security enablement
• Generates the exact remediation: the absolute URL with explicit scheme, the AwsSdk2Transport configuration block with the correct service name and region, the AWS SDK version bump, or the truststore update for the cluster's CA
• Surfaces client-side connection errors via client-perspective monitoring agents because cluster logs never see this exception (no request leaves the client) - the data has to come from outside the cluster

Pulse flags clusters that moved to HTTPS but still receive HTTP traffic from a subset of clients, which is the upgrade trap that produces UnknownServiceException at 3am on every redeploy.

Start a free trial to connect your cluster.

Frequently Asked Questions

Q: Is UnknownServiceException specific to Elasticsearch?
A: No. It is a JDK exception (java.net.UnknownServiceException) raised by URL handling, and an AWS SDK exception raised by request signing. It appears in any client code dealing with HTTP-like protocols. With Elasticsearch/OpenSearch, the common triggers are URL/scheme issues and AWS SDK signing.

Q: How do I sign requests to AWS-hosted OpenSearch correctly?
A: Use the AwsSdk2Transport (Java) or equivalent in other SDKs. The service name is es for managed clusters and aoss for OpenSearch Serverless. Region must match the cluster's region. Credentials must have the appropriate IAM permissions.

Q: Why does my client work locally but fail with UnknownServiceException in production?
A: Local clusters often allow plain HTTP without auth; production clusters use HTTPS with AWS SigV4 or Elastic API keys. The client's connection logic differs between environments and may not have been tested against the production scheme/auth combination.

Q: Can UnknownServiceException be caused by a network failure?
A: No. Network failures surface as ConnectException, SocketTimeoutException, or UnknownHostException. UnknownServiceException is purely a configuration/protocol issue and is thrown before any network I/O happens.

Q: Does this error indicate an Elasticsearch security misconfiguration?
A: Indirectly - clusters that move to HTTPS-only and TLS-required leave HTTP clients failing with various errors, sometimes including UnknownServiceException depending on the client library. The fix is on the client: switch to HTTPS and trust the cluster's CA.

Q: Should I retry UnknownServiceException?
A: No. The exception is deterministic - same configuration, same failure. Retrying will not help. Fix the URL scheme or signer configuration.

Q: What's the fastest way to diagnose UnknownServiceException in production?
A: Pulse, the AI DBA for Elasticsearch and OpenSearch, attributes the client-side exception to URL handler scheme, AWS SDK signing, or HTTPS-after-security mismatch by reading the stack trace and probing the cluster's actual scheme. It surfaces the misconfigured client identity since cluster logs never record this exception.

Related Reading

• Elasticsearch No alive nodes found in cluster: related connection failures.
• Elasticsearch Connection refused: the network-layer counterpart.
• Elasticsearch SocketTimeoutException: for established-connection timeouts.
• OpenSearch vs Elasticsearch: distribution differences.
• Elasticsearch monitoring: client-perspective monitoring.