Proxy URL format that clients actually parse

Encode usernames and passwords

Credentials live inside a URL. That means reserved URL characters matter. Encode the username and password if they contain symbols.

Client examples

# curl
                        curl -x http://USER:PASS@proxynade.net:2555 https://example.com -I
                        
                        # Python Requests
                        proxies = {
                            'http': 'socks5h://USER:PASS@proxynade.net:2555',
                            'https': 'socks5h://USER:PASS@proxynade.net:2555',
                        }
                        
                        # Playwright
                        proxy: {
                          server: 'http://proxynade.net:2555',
                          username: process.env.PROXY_USER,
                          password: process.env.PROXY_PASS
                        }

Notice the Playwright shape. It does not take the full credentialed URL in server. Some browser clients want split fields.

IPv6 needs brackets

An IPv6 host contains colons, so wrap it in brackets. Without brackets, the parser cannot tell where the host ends and the port begins.

http://USER:PASS@[2001:db8::10]:2555

When debugging, test the same proxy with curl first. Then move the exact pieces into the app.

Parse the URL before using it

Make the app parse and print the pieces without the password. This catches encoding bugs before the request touches the network.

const proxy = new URL(process.env.PROXY_URL);
                        
                        console.log({
                          protocol: proxy.protocol,
                          username: proxy.username,
                          passwordSet: proxy.password.length > 0,
                          hostname: proxy.hostname,
                          port: proxy.port
                        });

If hostname contains part of the password, the credentials were not encoded. If port is empty, the URL is missing the last separator or IPv6 brackets.

Connection string checklist

• Always include a scheme.
• Encode username and password separately.
• Use brackets around IPv6 hosts.
• Keep full URLs out of Playwright server.
• Use socks5h when proxy-side DNS matters.
• Test the exact line with curl -x.

Do not normalize away the scheme

Some internal config systems strip punctuation, lower-case fields, or split on colons. That can destroy a proxy line. Store the proxy as either a full URL string or structured fields. Do not bounce between both formats unless you have tests.

The safest production shape is often structured storage: scheme, host, port, username, password, and DNS mode. Generate the final URL at the edge where the client library needs it.

Decision rule

When support asks for the proxy line, send a redacted version that preserves structure: scheme://USER:PASS@host:port. That lets them spot parser mistakes without receiving secrets. Never paste live credentials into tickets, screenshots, or shared chat logs.

Proxy string FAQ

Is HTTPS target traffic possible through an HTTP proxy? Yes. The client uses CONNECT to reach the HTTPS target through the proxy.

Why does my password break the proxy URL? Reserved URL characters must be encoded. Raw @ and : are common failures.

Do all apps accept the full proxy URL? No. Some apps require separate host, port, username, and password fields.

What is the first test? Use curl -x with one small target before adding the line to a bigger app.