microg/GmsCore · error · IllegalArgumentException

A path must start with a single / .

Error message

A path must start with a single / .

What it means

PutDataRequest.create(String path) requires the path to start with exactly one '/'. If the path does not begin with '/', the library throws IllegalArgumentException("A path must start with a single / .") because a wear:// URI cannot be built from a relative path.

Source

Thrown at play-services-wearable/src/main/java/com/google/android/gms/wearable/internal/PutDataRequest.java:71

    private PutDataRequest() {
        uri = null;
        assets = new Bundle();
    }

    private PutDataRequest(Uri uri) {
        this.uri = uri;
        assets = new Bundle();
    }

    public static PutDataRequest create(Uri uri) {
        return new PutDataRequest(uri);
    }

    public static PutDataRequest create(String path) {
        if (TextUtils.isEmpty(path)) {
            throw new IllegalArgumentException("An empty path was supplied.");
        } else if (!path.startsWith("/")) {
            throw new IllegalArgumentException("A path must start with a single / .");
        } else if (path.startsWith("//")) {
            throw new IllegalArgumentException("A path must start with a single / .");
        } else {
            return create((new Uri.Builder()).scheme(WEAR_URI_SCHEME).path(path).build());
        }
    }

    public static PutDataRequest createFromDataItem(DataItem source) {
        PutDataRequest dataRequest = new PutDataRequest(source.getUri());
        dataRequest.data = source.getData();
        // TODO: assets
        return dataRequest;
    }

    public static PutDataRequest createWithAutoAppendedId(String pathPrefix) {
        return new PutDataRequest(null);
    }

View on GitHub (pinned to 157c9d86ac)

Solutions

1. Prepend '/' to the path if missing before calling create().
2. Use DataMap or PutDataRequest.create(Uri) with a properly built wear:// Uri if you need more control.
3. Normalize paths through a helper that guarantees a leading slash.

Example fix

// before
PutDataRequest request = PutDataRequest.create("steps");

// after
if (!path.startsWith("/")) {
    path = "/" + path;
}
PutDataRequest request = PutDataRequest.create(path);

if (path != null && !path.startsWith("/")) path = "/" + path;

try {
    PutDataRequest.create(path);
} catch (IllegalArgumentException e) {
    PutDataRequest.create("/" + path);
}

When it happens

Trigger: Calling PutDataRequest.create("foo") or create("data/item") — a non-empty path whose first character is not '/'.

Common situations: Passing just a key name instead of a path; stripping the leading slash in string manipulation; using a path fragment copied from documentation without the leading '/'.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• An empty path was supplied.
• maxUpdates must be greater than 0
• minUpdateDistanceMeters must be greater than or equal to 0
• minUpdateIntervalMillis must be greater than or equal to 0,
• Transparency must be in the range [0..1]

AI-assisted analysis of microg/GmsCore@157c9d86ac (2026-09-06). Data as JSON: /api/errors/3e47cd515b8dc7be. Report an issue: GitHub.