EC
ERR_UNESCAPED_CHARACTERS
Node.jsERRORNotableEncodingHIGH confidence

URL contains unescaped characters that are not allowed

Production Risk

Medium — always encode user-supplied URL components to prevent errors and security issues.

What this means

Thrown when a URL passed to an HTTP request contains characters that are not allowed in a URL without percent-encoding. These characters must be encoded before being included in a request path.

Why it happens
  1. 1Using spaces or special characters in URL paths without encoding them
  2. 2Building URLs from user input without applying encodeURIComponent()
  3. 3Copying a URL from a browser address bar that auto-decoded percent-encoded characters
How to reproduce

Triggered when the HTTP client validates a request URL and finds raw characters that must be percent-encoded.

trigger — this will error
trigger — this will error
const http = require('http');
http.request({
  hostname: 'localhost',
  path: '/search?q=hello world', // space is not allowed
});

expected output

Error [ERR_UNESCAPED_CHARACTERS]: Request path contains unescaped characters

Fix 1

Encode query parameters and path segments

WHEN When building URLs from dynamic values

Encode query parameters and path segments
const query = encodeURIComponent('hello world');
http.request({
  hostname: 'localhost',
  path: `/search?q=${query}`, // encoded: /search?q=hello%20world
});

Why this works

encodeURIComponent() percent-encodes characters that are not valid in URL components.

Fix 2

Use the URL API to construct safe URLs

WHEN When building complex URLs

Use the URL API to construct safe URLs
const url = new URL('http://localhost/search');
url.searchParams.set('q', 'hello world');
// url.href is 'http://localhost/search?q=hello+world'
http.request(url);

Why this works

The URL API handles encoding automatically when you set searchParams.

Code examples
Triggerjs
const http = require('http');
http.request({
  hostname: 'localhost',
  path: '/search?q=hello world', // space is not allowed
});  // this triggers ERR_UNESCAPED_CHARACTERS
Handle in try/catchjs
try {
  // operation that may throw ERR_UNESCAPED_CHARACTERS
  riskyOperation()
} catch (err) {
  if (err.code === 'ERR_UNESCAPED_CHARACTERS') {
    console.error('ERR_UNESCAPED_CHARACTERS:', err.message)
  } else {
    throw err
  }
}
Defensive pattern to avoid itjs
// Validate inputs before calling the operation
function safe_err_unescaped_characters(...args) {
  // validate args here
  return performOperation(...args)
}
What not to do

✕ Put raw user input directly into URL paths

Unencoded characters cause this error and may also enable path traversal or injection attacks.

Sources
Official documentation ↗

Node.js Error Codes Documentation

Content generated with AI assistance and reviewed for accuracy. Found an error? hello@errcodes.dev

← All Node.js errors