---
title: "url_decode | Speedscale Docs"
description: "Decode percent-encoded values with the url_decode transform in Speedscale — a one-way unescape using Go's path-unescape rules. Pair with url_encode to round-trip URL-escaped fields."
canonical: "https://docs.speedscale.com/guides/transformation/transforms/url_decode/"
---

[Documentation index](https://docs.speedscale.com/guides/llms.txt) | [Markdown](https://docs.speedscale.com/guides/transformation/transforms/url_decode/index.md) | [Canonical page](https://docs.speedscale.com/guides/transformation/transforms/url_decode/)

# url\_decode

The `url_decode` transform URL-unescapes a value, converting each `%AB` sequence back to the corresponding byte. It is **one-way** — the second phase does not re-encode, so the field is left in its decoded form when written back to the RRPair.

URL encoding and decoding are deliberately split into two transforms ([`url_decode`](https://docs.speedscale.com/guides/transformation/transforms/url_decode/) and [`url_encode`](https://docs.speedscale.com/guides/transformation/transforms/url_encode/)) so a chain can decide exactly when to re-encode.

*   **Transform type name (config/API):** `url_decode`
*   **Shorthand format:** `url_decode()`

<a id="quick-start"></a>

## Quick Start

Decode an encoded field so downstream transforms see the plain value:

```json
"type": "url_decode"
```

No configuration parameters.

<a id="how-it-works"></a>

## How It Works

1.  **First phase.** The extracted token is URL path-unescaped and passed to the next transform.
2.  **Second phase.** No-op. The decoded value flows through to the RRPair unchanged.

To round-trip — decode, modify, re-encode — chain `url_decode` at the front and [`url_encode`](https://docs.speedscale.com/guides/transformation/transforms/url_encode/) at the tail.

<a id="unescape-rules"></a>

### Unescape Rules

The transform unescapes percent-encoded sequences (Go `url.PathUnescape`):

| Input | Decoded as |
| --- | --- |
| `%20` | space |
| `%26` | `&` |
| `%3F` | `?` |
| `%40` | `@` |
| `%25` | `%` |
| `%2F` | `/` |
| `+` | `+` (kept as-is — path-unescape does **not** convert `+` to space) |

Note: in query-string semantics, `+` decodes to a space. Path-unescape leaves `+` alone. If your value is from a query string and uses `+`\-for-space, pre-process with [`replace`](https://docs.speedscale.com/guides/transformation/transforms/replace/) or use a different decoder.

<a id="invalid-input-raises-an-error"></a>

### Invalid Input Raises an Error

Unlike [`base64`](https://docs.speedscale.com/guides/transformation/transforms/base64/) (which silently passes through invalid input), `url_decode` returns an error if the input contains malformed escape sequences — a `%` not followed by two hexadecimal digits, for example. The chain surfaces this as a runtime decode error.

<a id="configuration"></a>

## Configuration

No configuration parameters.

<a id="examples"></a>

## Examples

<a id="example-1--decode-a-json-body-field"></a>

### Example 1 — Decode a JSON body field

```text
req_body() → json_path(path="user.encodedData") → url_decode()
```

*   `hello%20world%20%26%20special%20chars` → `hello world & special chars`

<a id="example-2--decode-then-re-extract-nested-json"></a>

### Example 2 — Decode then re-extract nested JSON

```text
req_header(name="X-Encoded-Info") → url_decode() → json_path(path="email")
```

The header carries percent-encoded JSON; `url_decode` produces the raw JSON so `json_path` can read `email` from it.

<a id="example-3--round-trip-decode-transform-re-encode"></a>

### Example 3 — Round-trip: decode, transform, re-encode

```text
req_body() → json_path(path="user.encodedData") → url_decode() → constant(value="foo") → url_encode()
```

Decode the value, replace with a constant, re-encode on the way out.

<a id="example-4--decode-an-email-like-value"></a>

### Example 4 — Decode an email-like value

*   `user%40example.com%3Fparam%3Dvalue` → `user@example.com?param=value`

<a id="common-misconceptions"></a>

## Common Misconceptions

1.  **"The chain auto-encodes on the way back."** No. `url_decode` is one-way. Add [`url_encode`](https://docs.speedscale.com/guides/transformation/transforms/url_encode/) at the end of the chain if you need the field re-encoded before insertion.
    
2.  **"`+` decodes to space."** Path-unescape leaves `+` alone. Query-string `+`\-for-space semantics are not applied. If your value uses `+`, normalize with [`replace`](https://docs.speedscale.com/guides/transformation/transforms/replace/) first.
    
3.  **"Invalid input is silently ignored."** No. A malformed escape (`%G1`, `%2`, etc.) returns an error. Compare with [`base64`](https://docs.speedscale.com/guides/transformation/transforms/base64/), which silently passes through bad input.
    

<a id="troubleshooting"></a>

## Troubleshooting

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| Runtime decode error | Input contains a `%` not followed by two hex digits | Sanitize the upstream value, or check whether the field is actually encoded |
| `+` still present in output | Path-unescape does not convert `+` to space | Use [`replace`](https://docs.speedscale.com/guides/transformation/transforms/replace/) to swap `+` for before or after `url_decode` |
| Value emitted decoded but downstream system expects encoded form | `url_encode` was not appended to the chain | Add [`url_encode`](https://docs.speedscale.com/guides/transformation/transforms/url_encode/) at the tail |
| Double-decoded result | Field was decoded twice in the chain | Remove the extra `url_decode` step |

<a id="related-transforms"></a>

## Related Transforms

*   [`url_encode`](https://docs.speedscale.com/guides/transformation/transforms/url_encode/) — the inverse first-phase transform. Pair with `url_decode` to round-trip.
*   [`base64`](https://docs.speedscale.com/guides/transformation/transforms/base64/) — two-phase decode/re-encode for base64-wrapped fields.
*   [`replace`](https://docs.speedscale.com/guides/transformation/transforms/replace/) — for ad-hoc character fixes that path-unescape rules do not cover (e.g. `+`\-for-space).
