Skip to main content

How to Resolve the "TypeError: Request path contains unescaped characters" Error in JavaScript

The TypeError [ERR_UNESCAPED_CHARACTERS]: Request path contains unescaped characters is a common error in Node.js (and a similar issue occurs in browsers) when you try to make an HTTP request using a URL string that contains illegal characters, such as spaces or certain symbols.

To solve this error, you must properly URL-encode your URL string before making the request. This guide will explain the difference between encodeURI() and encodeURIComponent() and show you how to use the modern URL constructor to handle this correctly.

The Core Problem: Unescaped Characters in URLs​

A URL can only contain a specific set of characters. Any character outside this set, such as a space, %, ^, or |, must be "escaped" or "percent-encoded" (e.g., a space becomes %20). When an HTTP client like fetch or axios receives a string with these unescaped characters, it throws an error to prevent a malformed request from being sent.

Example of problem:

import fetch from 'node-fetch'; // Or any HTTP client

// Problem: The URL contains spaces and a '%' sign.
let url = 'https://api.example.com/search?q=reports & invoices %';

// ⛔️ TypeError [ERR_UNESCAPED_CHARACTERS]: Request path contains unescaped characters
fetch(url);

This function is designed to encode a component of a URI, such as a query string parameter, a path segment, or a hash. It is aggressive and will encode reserved characters like /, ?, :, &, and =. This is what you want for encoding dynamic user input.

let baseUrl = 'https://api.example.com/search';
let userQuery = 'reports & invoices %';

// ✅ Correct: Encode ONLY the dynamic part of the URL.
let encodedQuery = encodeURIComponent(userQuery);
// encodedQuery is now "reports%20%26%20invoices%20%25"

let fullUrl = `${baseUrl}?q=${encodedQuery}`;
console.log(fullUrl); // Output: "https://api.example.com/search?q=reports%20%26%20invoices%20%25"

// This URL is now safe to use in a fetch request.
// fetch(fullUrl);
note

This is the recommended best practice when building a URL from dynamic data.

Solution 2 (For full URLs): encodeURI()​

This function is designed to encode a full URI. It is less aggressive than encodeURIComponent() and will not encode reserved characters that have special meaning in a URL (like &, ?, /, #).

// This URL has a space in its path.
let url = 'https://example.com/some path with spaces';

let encodedUrl = encodeURI(url);
console.log(encodedUrl); // Output: "https://example.com/some%20path%20with%20spaces"

// fetch(encodedUrl);

Solution 3 (Modern & Robust): The URL Constructor​

The modern URL constructor, available in both Node.js and browsers, is a powerful and robust tool for building and encoding URLs. It handles a lot of the encoding for you automatically.

let baseUrl = 'https://api.example.com/search';
let userQuery = 'reports & invoices %';

// 1. Create a URL object from the base URL.
let urlObject = new URL(baseUrl);

// 2. Append the search parameter. The `searchParams.set()` method
//    automatically handles the encoding for you.
urlObject.searchParams.set('q', userQuery);

// 3. The .href property returns the fully constructed and encoded URL string.
let fullUrl = urlObject.href;

console.log(fullUrl);
// Output: "https://api.example.com/search?q=reports+%26+invoices+%25"

// fetch(fullUrl);
note

This is the safest and most recommended method for building complex URLs with query parameters, as it eliminates manual encoding errors.

encodeURI() vs. encodeURIComponent(): A Critical Distinction​

Choosing the wrong function can break your URL.

  • encodeURI(): Use this when you have a full URL that might contain illegal characters. It will not encode characters like /, ?, &, etc.
  • encodeURIComponent(): Use this when you are encoding a piece of a URL that will be inserted into a larger URL (like a query parameter).

Never use encodeURIComponent() on a full URL. It will break the URL by encoding the special characters.

// ⛔️ INCORRECT
let badUrl = encodeURIComponent('https://example.com?q=test');
// Output: "https%3A%2F%2Fexample.com%3Fq%3Dtest" (This is a broken URL)

Conclusion​

The "Request path contains unescaped characters" error is a signal that you need to properly encode your URL before making an HTTP request.

  • When building a URL with dynamic data (like user input for a query), the recommended best practice is to use the URL constructor and its searchParams property, as it handles all encoding automatically.
  • If you are building the URL manually, use encodeURIComponent() on each individual component (path segments, query values).
  • Only use encodeURI() to fix a pre-existing, full URL string that contains unescaped characters like spaces.

Table of Contents