agent didn't URL-encode path parameters - emails used as IDs broke every user-lookup call

TL;DR

URL-encode every path parameter before inserting it into the URL, and the lookups work. An unencoded @ in a path breaks routing; encoded as %40 it travels safely.

Encode at the boundary where the parameter enters the URL, in one helper, so no call site can forget it.

Verbatim query

agent didn't URL-encode path parameters  -  emails used as IDs broke every user-lookup call

Steps

1. Reproduce with a raw email in the path Build the lookup URL with the email unencoded and log the full URL. Send it and record the failure - 404, 400, or a wrong-user response. Expected: The unencoded URL visibly contains the raw @ and the call fails.

2. Verify the encoded version works Encode the email and resend the identical lookup. Confirm the correct user record comes back. Expected: The encoded URL returns the right user, proving encoding was the issue.

3. Add a path-encoding helper Write one function that encodes a single path segment and nothing else. Use it for every parameter interpolated into a path. Expected: All path parameters pass through the encoder.

4. Audit every path interpolation Search for URL building with format strings or concatenation that inserts variables. Route each through the helper. Expected: No raw variable lands in a path anywhere in the client.

5. Add an encoding test Test that an email ID produces a URL with %40 and no raw @. Include + and spaces in the test cases. Expected: The test passes and would catch a regen that drops encoding.

Use this when

• User lookups by email or other special-character IDs fail
• The logged URL contains raw @ or + in the path
• Lookups work for simple numeric IDs but break for email IDs

Not for this skill when

• The path is encoded and lookups still fail - the ID value itself may be wrong
• Failures are in query parameters, not the path - check query encoding separately
• The API expects the raw email in the path by design - rare, but check the docs

Variant phrasings

email as path parameter breaks

Emails contain @ and + and dots; paths treat those as structural characters unless encoded.

unencoded path parameter 404

A raw @ in a path can split routing in surprising ways on strict servers.

URL encode path segments

Encode each segment individually - encoding the whole URL double-encodes the slashes.

Why it happens

URLs have structure: slashes separate segments, @ separates userinfo, + means space in queries. An email dropped raw into a path collides with that structure, so the server parses a different path than you intended. Encoding translates the email's special characters into safe sequences the server decodes back after routing. The fix belongs in one helper because every call site will otherwise forget it eventually.

Edge cases

• Encode segments, not the whole URL: encoding the full URL turns real slashes into %2F and breaks routing
• Some frameworks encode path params automatically - know whether yours does before adding a second layer
• Double encoding (%2540) is the tell that two layers both encoded; decode once or encode once, not both

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_J9H7l7zmg8nfhZ9hkTxDpQ