clockworklabs/SpacetimeDB · error

Route paths must start with `/`: {path}

Error message

Route paths must start with `/`: {path}

What it means

assert_valid_path rejects any non-empty route path that does not begin with '/'. Router construction methods (route, nest) validate every path string, so a missing leading slash panics immediately at router-build time rather than failing at request matching.

Source

Thrown at crates/bindings/src/http.rs:411

}

#[cfg(feature = "unstable")]
fn join_paths(prefix: &str, suffix: &str) -> String {
    if prefix == "/" {
        return suffix.to_string();
    }
    if suffix == "/" {
        return prefix.to_string();
    }
    let prefix = prefix.trim_end_matches('/');
    let suffix = suffix.trim_start_matches('/');
    format!("{prefix}/{suffix}")
}

#[cfg(feature = "unstable")]
fn assert_valid_path(path: &str) {
    if !path.is_empty() && !path.starts_with('/') {
        panic!("Route paths must start with `/`: {path}");
    }
    if !path.chars().all(character_is_acceptable_for_route_path) {
        panic!(
            "Route paths may contain only {}: {path}",
            ACCEPTABLE_ROUTE_PATH_CHARS_HUMAN_DESCRIPTION
        );
    }
}

#[cfg(feature = "unstable")]
fn routes_overlap(a: &RouteSpec, b: &RouteSpec) -> bool {
    if a.path != b.path {
        return false;
    }
    matches!(a.method, MethodOrAny::Any) || matches!(b.method, MethodOrAny::Any) || a.method == b.method
}

/// Allows performing HTTP requests via [`HttpClient::send`] and [`HttpClient::get`].

View on GitHub (pinned to 6dee26c6ef)

Solutions

1. Add the leading slash to the path in the panic message.
2. If paths come from config or format!, normalize them with a helper that prepends '/' when missing.
3. Use join_paths-style construction (prefix ends with '/', suffix starts with '/') when composing paths.

Example fix

// before
let r = Router::new().route(Method::GET, "users", list); // panics

// after
let r = Router::new().route(Method::GET, "/users", list);

fn normalize_route_path(p: &str) -> String {
    if p.starts_with('/') { p.to_string() } else { format!("/{p}") }
}
assert!(normalize_route_path("/users").starts_with('/'));

When it happens

Trigger: Passing "users" instead of "/users" to .route(...) or .nest(...); building paths dynamically with format! or env vars that omit the leading slash; joining an empty prefix incorrectly so the slash is lost.

Common situations: Porting handlers from frameworks where paths are relative (actix-style "/x" vs template-relative strings); config-driven route registration where the config file omits the slash.

Related errors

• Route paths may contain only {}: {path}
• Route paths must start with `/`: {path}
• Route paths may contain only {AcceptableRoutePathCharsHumanD
• Cannot nest router at `{path}`; existing routes overlap with
• Route conflict for `{path}`

AI-assisted analysis of clockworklabs/SpacetimeDB@6dee26c6ef (2026-08-20). Data as JSON: /api/errors/2d3941552ab5fef3. Report an issue: GitHub.