docs: clarify Astro.url and Astro.params runtime behavior by Prayaksh · Pull Request #13903 · withastro/docs

Prayaksh · 2026-05-17T12:27:22Z

Description (required)

This PR clarifies the runtime behavior of URL decoding in Astro v6 dynamic routes.

The original issue was reported in the withastro/astro repository, and after maintainer confirmation it was identified as a documentation gap rather than a runtime bug.

In Astro v6, Astro.url returns a normalized and partially decoded URL, which may differ from new URL(Astro.request.url). Additionally, Astro.params values are automatically decoded. This behavior was not clearly documented in the v6 upgrade guide section covering percent-encoded routes.

This update adds a runtime clarification under the “Percent-Encoding in routes” section to reflect the actual behavior and avoid confusion for users working with encoded dynamic route segments.

Related issues & labels (optional)

Closes URL Decoding in Dynamic Routes (SSR) astro#16313
Suggested label: documentation

netlify · 2026-05-17T12:27:26Z

✅ Deploy Preview for astro-docs-2 ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`16481ea`
🔍 Latest deploy log	https://app.netlify.com/projects/astro-docs-2/deploys/6a1a7bc73e15410008118fc8
😎 Deploy Preview	https://deploy-preview-13903--astro-docs-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

To edit notification comments on pull requests, go to your Netlify project configuration.

astrobot-houston · 2026-05-17T12:27:48Z

Hello! Thank you for opening your first PR to Astro’s Docs! 🎉

Here’s what will happen next:

Our GitHub bots will run to check your changes.
If they spot any broken links you will see some error messages on this PR.
Don’t hesitate to ask any questions if you’re not sure what these mean!
In a few minutes, you’ll be able to see a preview of your changes on Netlify 🥳.
One or more of our maintainers will take a look and may ask you to make changes.
We try to be responsive, but don’t worry if this takes a few days.

astrobot-houston · 2026-05-17T12:27:52Z

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the ignoreKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

File	Note
en/guides/upgrade-to/v6.mdx	Source changed, localizations will be marked as outdated.
en/reference/api-reference.mdx	Source changed, localizations will be marked as outdated.

Warnings reference

Icon	Description
🔄️	The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

ArmandPhilippot

Thanks for your contribution!

If this is indeed a documentation issue (I wouldn't say "probably" means "confirmation"), this addition can be helpful but it doesn't fully fix the issue.

The issue mentions a misleading description in https://docs.astro.build/en/reference/api-reference/#url and potentially in https://docs.astro.build/en/reference/api-reference/#params

@ematipico can you confirm we should fix the docs? Or the fix mentioned by the bot could work and no docs change is required?

Edit: I hadn't followed the linked PR, it seems this might have been fixed in withastro/astro#16808 ?

Prayaksh · 2026-05-21T19:15:44Z

I realize now that I acted on the “probably” comment before the issue was fully confirmed. Thank you for clarifying. I’m still learning the process and will make sure to verify before updating the docs in the future.

ematipico · 2026-05-22T08:24:47Z

The documentation update is still valid, because not all characters can be safely decoded e.g. %25AB. Even after my fix, there are still cases that are uncertain, so Astro play it safe and returns an error.

ArmandPhilippot · 2026-05-22T09:58:56Z

Okay, thanks Ema!

And no problem @Prayaksh! Are you still willing to check if other pages require an update? It seems we at least need to update https://docs.astro.build/en/reference/api-reference/#url

Prayaksh · 2026-05-23T12:52:45Z

Thanks @ArmandPhilippot ! I’ve updated the Astro.url and Astro.params API reference docs to clarify the normalization/decoding behavior as well.

ArmandPhilippot

Thanks for the update! But, I think the upgrade guide addition is misplaced and your description for Astro.params doesn't seem correct.

ArmandPhilippot · 2026-05-25T15:26:26Z

+
+`Astro.params` values are automatically decoded, and percent-encoded characters in pathnames or parameters (like `%25`) may appear decoded in `Astro.url` or `Astro.params`.
+
+If you need the raw request URL with no decoding, use `Astro.request.url` and parse it manually.


This doesn't seem to be the right place:

In "What should I do?" we explain what the user should do based on the change describe above. Here we are explaining that something else has changed without explaining what the user should do.

This is in the "Removed: Percent-Encoding in routes" section... but here we are not explaining something that has been removed but changed. Even, if this is tied to the same PR, it seems doesn't feel right.

I think we need a new section in "Breaking changes" instead. Probably something similar to this one https://docs.astro.build/en/guides/upgrade-to/v5/#changed-params-no-longer-decoded in the v5 upgrade guide.

Prayaksh · 2026-05-29T10:25:38Z

tried to change as suggested.

thanks!

ematipico · 2026-05-29T13:14:32Z

+A normalized [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL) object derived from the current `request.url` value. It is useful for interacting with individual properties of the request URL, like pathname and origin. 

-`Astro.url` is equivalent to doing `new URL(Astro.request.url)`.
+Since Astro v6, the pathname is partially decoded during route normalization. This means `Astro.url.pathname` may differ from `new URL(Astro.request.url).pathname` for percent-encoded route segments.


Suggested change

Since Astro v6, the pathname is partially decoded during route normalization. This means `Astro.url.pathname` may differ from `new URL(Astro.request.url).pathname` for percent-encoded route segments.

Since Astro v6, the pathname may be partially decoded during route normalization. This means `Astro.url.pathname` may differ from `new URL(Astro.request.url).pathname` for percent-encoded route segments.

It's not always the case, so maybe using "may" sounds better

ArmandPhilippot

Thanks for the update but, in addition to Ema suggestion, I see two issues:

configuration-reference.mdx contains unrelated changes
the upgrade guide section is misplaced:

ArmandPhilippot · 2026-05-29T13:33:40Z

+## Changed: Route pathname normalization
+
+Since Astro v6, route pathnames are partially decoded during route normalization. This means `Astro.url.pathname` may differ from `new URL(Astro.request.url).pathname` for percent-encoded route segments.
+
+This also affects route params derived from normalized pathnames.
+
+### What should I do?
+
+If you need access to the original encoded pathname, use `new URL(Astro.request.url).pathname` instead of `Astro.url.pathname`.
+


This should be an h3 (instead of h2) and h4 (instead of h3) and moved to the Breaking changes section.

ArmandPhilippot · 2026-05-29T13:37:29Z

+When deploying behind reverse proxies or serverless platforms (for example Vercel), configure `allowedDomains` so Astro can safely trust forwarded host headers during origin validation.
+


As stated at the beginning of this file, it is read-only and auto-generated from the main repo. So, any change should be made in the withastro/astro repo instead.
But, anyway, this sounds unrelated to this PR or the issue.

Prayaksh · 2026-05-30T05:58:58Z

Sorry for the confusion — my previous commit accidentally included an unrelated change. I've corrected the commit and updated the branch so the PR now only contains the intended documentation changes.

I also wasn't able to identify the source PR for this behavior change. If there's a specific PR number that should be referenced, please let me know.

docs: clarify Astro.url and Astro.params runtime behavior

4c68460

ArmandPhilippot reviewed May 21, 2026

View reviewed changes

ArmandPhilippot added improve or update documentation Enhance / update existing documentation (e.g. add example, improve description, update for changes) should this be documented? Need to figure out whether this is something to add to documentation or not labels May 21, 2026

ArmandPhilippot removed the should this be documented? Need to figure out whether this is something to add to documentation or not label May 22, 2026

docs: clarify Astro.url and params normalization

4a89ecd

ArmandPhilippot reviewed May 25, 2026

View reviewed changes

ematipico reviewed May 29, 2026

View reviewed changes

ArmandPhilippot reviewed May 29, 2026

View reviewed changes

docs: clarify route pathname normalization

16481ea

Prayaksh force-pushed the fix/astro-url-runtime-docs branch from 440fed4 to 16481ea Compare May 30, 2026 05:55


		`Astro.params` values are automatically decoded, and percent-encoded characters in pathnames or parameters (like `%25`) may appear decoded in `Astro.url` or `Astro.params`.

		If you need the raw request URL with no decoding, use `Astro.request.url` and parse it manually.

	Since Astro v6, the pathname is partially decoded during route normalization. This means `Astro.url.pathname` may differ from `new URL(Astro.request.url).pathname` for percent-encoded route segments.
	Since Astro v6, the pathname may be partially decoded during route normalization. This means `Astro.url.pathname` may differ from `new URL(Astro.request.url).pathname` for percent-encoded route segments.

		When deploying behind reverse proxies or serverless platforms (for example Vercel), configure `allowedDomains` so Astro can safely trust forwarded host headers during origin validation.

Uh oh!

Conversation

Prayaksh commented May 17, 2026

Description (required)

Related issues & labels (optional)

Uh oh!

netlify Bot commented May 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for astro-docs-2 ready!

Uh oh!

astrobot-houston commented May 17, 2026

Uh oh!

astrobot-houston commented May 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Lunaria Status Overview

Tracked Files

Uh oh!

ArmandPhilippot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Prayaksh commented May 21, 2026

Uh oh!

ematipico commented May 22, 2026

Uh oh!

ArmandPhilippot commented May 22, 2026

Uh oh!

Prayaksh commented May 23, 2026

Uh oh!

ArmandPhilippot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ArmandPhilippot May 25, 2026

Choose a reason for hiding this comment

Uh oh!

Prayaksh commented May 29, 2026

Uh oh!

ematipico May 29, 2026

Choose a reason for hiding this comment

Uh oh!

ArmandPhilippot left a comment

Choose a reason for hiding this comment

Uh oh!

ArmandPhilippot May 29, 2026

Choose a reason for hiding this comment

Uh oh!

ArmandPhilippot May 29, 2026

Choose a reason for hiding this comment

Uh oh!

Prayaksh commented May 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

netlify Bot commented May 17, 2026 •

edited

Loading

astrobot-houston commented May 17, 2026 •

edited

Loading

ArmandPhilippot left a comment •

edited

Loading