github/copilot-sdk · error · IllegalArgumentException

UriRuntimeConnection url must be a non-empty string

Error message

UriRuntimeConnection url must be a non-empty string

What it means

UriRuntimeConnection's package-private constructor validates its url argument and throws IllegalArgumentException when it is null or the empty string. The library requires every runtime connection to carry a usable URL before any connection logic runs, so empty/unset URLs fail fast at construction time rather than producing confusing failures later during connect.

Solutions

1. Set a valid, non-empty runtime URL before constructing UriRuntimeConnection
2. Check the config source (env var, properties file) that supplies the URL — it is likely missing, blank, or under a renamed key
3. Log/inspect the value passed to the constructor at the call site to confirm it is null vs empty
4. If the URL is legitimately optional, guard the construction site and skip/defer creating the connection

Example fix

// before
UriRuntimeConnection conn = new UriRuntimeConnection(config.get("runtime.url"));
// after
String url = config.get("runtime.url");
if (url == null || url.isEmpty()) {
    throw new IllegalStateException("runtime.url is not configured");
}
UriRuntimeConnection conn = new UriRuntimeConnection(url);

if (url == null || url.isEmpty()) {
    throw new IllegalStateException("runtime.url must be configured before creating UriRuntimeConnection");
}
UriRuntimeConnection conn = new UriRuntimeConnection(url);

static boolean isValidUrl(String url) {
    return url != null && !url.isEmpty();
}

try {
    UriRuntimeConnection conn = new UriRuntimeConnection(url);
} catch (IllegalArgumentException e) {
    // url was null/empty: log config key and fail with actionable message
}

When it happens

Trigger: Calling the UriRuntimeConnection constructor (directly or via a factory/builder) with url == null or url == "" — e.g. reading a runtime endpoint from an unset config property or environment variable and passing it straight through.

Common situations: Config file or env var for the runtime endpoint is missing or blank; a properties loader returns empty strings for absent keys; a migration or version change renamed the endpoint key so the old lookup now returns null/empty; a builder was used without calling the url setter.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• CliUrl is mutually exclusive with CliPath
• TcpConnectionToken must be a non-empty string
• Invalid value ' '. Expected 'inprocess', 'stdio', or unset.
• sessionFs.initialCwd is required
• sessionFs.sessionStatePath is required

AI-assisted analysis of github/copilot-sdk@cd8cf15dc3 (2026-09-09). Data as JSON: /api/errors/b640f882b3735a88. Report an issue: GitHub.

Appendix: source

Thrown at java/sdk/src/main/java/com/github/copilot/rpc/UriRuntimeConnection.java:23

package com.github.copilot.rpc;

import com.github.copilot.CopilotExperimental;

/**
 * Connects to an already-running runtime at the configured URL. Construct with
 * {@link RuntimeConnection#forUri(String)}.
 *
 * @since 1.0.0
 */
@CopilotExperimental
public final class UriRuntimeConnection extends RuntimeConnection {

    private final String url;
    private String connectionToken;

    UriRuntimeConnection(String url) {
        if (url == null || url.isEmpty()) {
            throw new IllegalArgumentException("UriRuntimeConnection url must be a non-empty string");
        }
        this.url = url;
    }

    /**
     * Returns the URL of the runtime to connect to.
     *
     * @return the URL; accepts {@code "port"}, {@code "host:port"}, or a full URL
     */
    public String getUrl() {
        return url;
    }

    /**
     * Returns the shared secret used to authenticate the connection.
     *
     * @return the token, or {@code null} if the runtime does not require one
     */

View on GitHub (pinned to cd8cf15dc3)