Summary

encode() in lib/helpers/buildURL.js deliberately decodes %3A, %24, %2C and %20 back to :, $, , and + for readability. Those characters are valid in a query component under RFC 3986, so the output is correct, but some backends require strict percent-encoding and reject the readable form.

axios already supports this case via paramsSerializer.encode, but it isn't documented with a strict-encoding example. Users hitting this run into it as a surprise (see the recurring stream of issues and PRs around %3A, e.g. #7290), and the workaround they often reach for is a one-off patch to encode() rather than the supported escape hatch.

What to add to the docs

A short subsection under paramsSerializer showing the strict-encoding case:

// Per-request: emit RFC 3986 strict percent-encoding for query values
axios.get('/foo', {
  params: { filter: JSON.stringify({ startedAt: '2025-01-23' }) },
  paramsSerializer: { encode: encodeURIComponent }
});

// Or set it on the instance defaults
const client = axios.create({
  paramsSerializer: { encode: encodeURIComponent }
});

Plus a one-line note explaining why the default decodes :, $, ,, +: those characters are valid in the query component per RFC 3986, axios prefers the readable form, but stricter servers may require full encoding via the option above.

Where

README.md paramsSerializer section, and the same section in docs/ if it lives there separately.

Related

• fix(buildURL): preserve encoded colon (%3A) for JSON-stringified params #7290 (closed) — proposed an in-encoder JSON-shape heuristic; the right answer is the existing paramsSerializer.encode hook.