topic Re: Problem while proxying public and private pages (CMS React) in CMS Development

Problem while proxying public and private pages (CMS React)

FPConnect — Wed, 05 Nov 2025 10:28:08 GMT

Hi everyone!

I’m having an issue while proxying private pages locally when developing with CMS React.
I’m using projects version 2025.2. I built a theme with React, and now I want to use the template I created for private pages.

According to the documentation:
https://developers.hubspot.com/docs/cms/reference/react/local-development

I should:

Open the page online and log in.
Add to the domain in the URL "hslocal.net:3000" to preview local changes while proxying the live page.

However, this doesn’t seem to work.

I've tried several approaches, but I always end up with one of the following results:

A new login screen appears (and the login does not work).
If I copy the cookies from the live page to the proxied one, I get an empty body with the following comment:

I initially thought the issue might be with my theme, so I created a new theme from the official HubSpot React boilerplate, without making any modifications - but I still get the same errors.

I also tried proxying public pages, just to check, and in that case I also get the same “Missing Template” error.

Additionally, I tried using the "Open Local Dev Server" option directly from the live page menu:

On Brave (with all shields disabled), I get a message saying the proxy is unavailable and to try again.
On Safari, with the local server running, I get a message saying the local server is not running.

So at this point I'm a bit stuck.
How is this supposed to work?
Is there something missing in the setup, or is there a known issue with proxying private pages in the latest version?

Thanks in advance for any help!

Re: Problem while proxying public and private pages (CMS React)

BérangèreL — Wed, 05 Nov 2025 11:25:46 GMT

Hi @FPConnect and welcome, we are so glad to have you here!

Great question, thanks for asking the HubSpot Community!

Here is an article that might help you: "Modules."

Now, let's consult our Top Experts: Hi @Anton, @nickdeckerdevs1 and @BelBarakat do you have any insights to share with @FPConnect, please?

Have a wonderful day and thanks so much!
Bérangère

Re: Problem while proxying public and private pages (CMS React)

nickdeckerdevs1 — Mon, 10 Nov 2025 10:29:57 GMT

Without digging in a bunch more, very hard to understand right now what is going on. It looks like something is incorrect with the theme possibly.

if you install the theme, are you able to create a page? When I debug my templates I use ?hsDebug=true in the url params and then inspect the code. That's how you would see those missing template errors and what not. So maybe there is more there. Either way - did you follow the path to the missing template? Is there a template missing at the path? You can search by file name through your repo or traverse through the folders and see what is going on there. If you states there is no actual template missing, I apologize. I'm going to assume that the template not rendering is going to cause issues.

I don't know how different this is from a react theme or a theme built in projects .2 -- however it should be the same.

Very hard to tell, you say you do a new theme project, and it still doesn't work. Have you upgraded all packages? Have you tried just an empty template with very little dependencies?

also are you only testing in safari and brave? This seems like an odd choice in a place to start.

Moderator note: While this solution may not address the original poster’s specific situation, it could be helpful for other community members facing similar challenges.

Re: Problem while proxying public and private pages (CMS React)

FPConnect — Wed, 05 Nov 2025 12:08:46 GMT

Yes, the theme is installed and I can create pages without any issues.
The “missing template” error only appears after I manually copy the cookies from the private page, or when I use a public page.
Since I need to test private pages, the main issue is that when I try to proxy the private page after logging in, I get prompted to log in again.

On public pages, when I add the debug parameter, I can see a bit more detail about the missing template error.

Locally, I can see the templates, and the templates work correctly when creating pages online.
But when trying to proxy the page, it doesn’t work.

I also thought the issue might be with my theme, which is why I started from scratch, with all packages updated, using only the HubSpot boilerplate, without adding anything.
But I still get the same problems (both on public and private pages).

That’s why it seems strange that the templates can’t be found and the proxy doesn’t work, especially when using the starter theme provided by HubSpot.

I’m using Brave and Safari because they’re the only browsers I currently have installed on my machine: Brave is what I use every day, and Safari is my backup to check whether Brave is blocking any scripts.
I will try with other browsers, but I don't think that makes any difference.

Re: Problem while proxying public and private pages (CMS React)

BérangèreL — Mon, 10 Nov 2025 10:27:31 GMT

Hi @FPConnect and welcome, we are so glad to have you on the HubSpot Community!

Regarding the "missing template" error: The error occurs because when proxying pages, the local dev server needs to find your templates with the .hubl.html extension.

Please make sure that:

- Your templates are renamed to include .hubl (e.g., template.hubl.html)
- Classic HubL modules are in a hubl-modules directory
- Module files also use .hubl extensions (e.g., module.hubl.html, module.hubl.css)

For the private page authentication issues, when proxying private/membership pages, you need to authenticate first on the live page, then add hslocal.net:3000 or localhost:3000 to the domain. To view as a specific contact, add ?email=contact@email.com to the URL.

Try using the --ssl option: Start the dev server with hs-cms-dev-server . --ssl to enable HTTPS proxying, which may resolve authentication issues.

If issues persist after verifying your file structure matches the project requirements, please share your theme-hsmeta.json configuration and confirm you're on the latest @hubspot/cms-dev-server version.

Hi @nickdeckerdevs1, @Anton and @BelBarakat do you have other suggestions to help @FPConnect, please?

Have a great day and thanks so much!
Bérangère

This post was created with the assistance of AI tools.

Re: Problem while proxying public and private pages (CMS React)

FPConnect — Mon, 10 Nov 2025 13:53:53 GMT

Hi @BérangèreL

Thanks for the detailed reply!

Just to clarify:

All of my templates already use the .hubl.html extension.
The module files are correctly named and structured.
The project layout matches the expected file/folder conventions.

To rule out any issue with my code, I did a clean test:

I updated all packages to the latest versions.
I created a brand-new theme using the official CMS React starter (the boilerplate provided by HubSpot).
I did not modify any file from the starter theme.

Even in this scenario, I get exactly the same errors, both on public and private pages, when proxying.
So it doesn’t seem to be something specific to my custom theme.

Regarding authentication: I am already following the documented flow - I log in first on the live page, then add to the the domain hslocal.net:3000 to proxy.
But the proxied page keeps redirecting me to a login page, and the login there doesn’t work (which makes sense, since it’s being proxied).
So the authentication never completes.

I also tried using --ssl, same result.

For reference, here is my theme-hsmeta.json (it is identical in both my theme and the starter boilerplate, untouched):

{ "uid": "theme", "type": "theme", "config": { "themePath": "my-theme", "secretNames": [] } }

And yes, I'm using the latest version of @hubspot/cms-dev-server.

Re: Problem while proxying public and private pages (CMS React)

BérangèreL — Tue, 11 Nov 2025 12:07:07 GMT

Hi @FPConnect and thanks for sharing all the detailed troubleshooting steps you’ve taken, it really helps clarify the scenario.

Since you've confirmed the structure, updated everything, and replicated the issue using the official CMS React starter, it sounds like the proxying problem may be related to authentication and session handling with private pages when using the local dev server.

Proxying private pages should work, but authentication must happen on the live page first, not through the proxy, is that the case for you?

Let's consult our Top Experts: Hi @nickdeckerdevs1, @zach_threadint and @sylvain_tirreau do you have suggestions to help @FPConnect, please?

Have a great day and thanks so much!
Bérangère

Re: Problem while proxying public and private pages (CMS React)

FPConnect — Tue, 11 Nov 2025 15:07:23 GMT

Hi @BérangèreL, thank you for your message and for looping in the others, I appreciate it.

Just to clarify an important point: the issue is not limited to private pages. I am also experiencing errors when proxying public pages. In those cases there is obviously no authentication involved, yet I get the missing template error.

So the problem seems independent from the login/session flow.

Happy to provide more details if needed, thanks again for your support.

Re: Problem while proxying public and private pages (CMS React)

BérangèreL — Thu, 13 Nov 2025 17:16:39 GMT

Hi @FPConnect and thanks for the additional information!

According to the local development documentation, when proxying pages you should access them via:

http://cmssite.com.hslocal.net:3000/page
http://cmssite.com.localhost:3000/page

For private pages specifically, you need to authenticate first on the live page, then add hslocal.net:3000 or localhost:3000 to the domain.

Since you're getting template errors on both public and private pages, this suggests indeed that the issue isn't authentication-related.

The problem may be with how the proxy is resolving templates.

Try checking that your local dev server is running properly and that the templates exist in your deployed project.

Here are related resources for you:

- Local development
- Proxying private pages
- Debugging methods and error types

@sylvain_tirreau, @SteveHTM and @MichaelMa any ideas on what could be the issue to help @FPConnect, please?

Have a wonderful day and thanks so much!
Bérangère

This post was created with the assistance of AI tools.

Re: Problem while proxying public and private pages (CMS React)

sylvain_tirreau — Fri, 14 Nov 2025 10:28:01 GMT

HI @FPConnect ,

With HubSpot projects (React CRM), we use `hs project dev` in the project root, while with a classic Hubl theme we use hs-cms-dev-server <theme-folder>. Are you following this correctly?

Do your templates have the .hubl.html extension?

In the theme-hsmeta.json file, the variables uid and themePath dictate the name of the /themes/<uid> folder.

For example, in src/theme/theme-hsmeta.json, if you define this:

{ "uid": "FPConnect-Theme", "type": "theme", "config": { "themePath": "my-theme" } }

a page that displays the template "/themes/FPConnect-Theme/templates/home.hubl.html" should find the template in "src/theme/my-theme/templates/home.hubl.html".

Re: Problem while proxying public and private pages (CMS React)

FPConnect — Fri, 14 Nov 2025 14:57:55 GMT

Hi @BérangèreL

The issues are actually two separate ones:

Public pages
When proxying public pages, I consistently get the “template missing” error, even though the templates are deployed and work correctly on the live environment.
Private pages
I follow the correct flow:
- authenticate first on the live page,
- then append hslocal.net:3000 to the URL.
However, instead of letting me access the proxied private page, HubSpot redirects me back to the login page, making it impossible to work locally with authenticated pages.

So the problem is not authentication, nor the templates themselves - it seems the proxy is failing in both scenarios, but in two different ways.

Thanks again!

Re: Problem while proxying public and private pages (CMS React)

FPConnect — Fri, 14 Nov 2025 15:25:23 GMT

Hi @sylvain_tirreau, thanks for your message.

I’d like to clarify a few points, because the documentation for CMS React (HubSpot Projects) states very clearly that the correct command for local development is npm run start, as written here:
https://developers.hubspot.com/docs/cms/reference/react/local-development

As already mentioned in previous posts:

all my templates do have the .hubl.html extension;
to make sure the issue wasn’t related to my theme, I ran several tests using the official HubSpot starter template, and the problem still occurs every single time.

To help reproduce the issue, here are the exact steps:

npx @hubspot/create-cms-theme@latest
Choose a theme name
Select TypeScript: yes
Choose directory
Automatic installation of CLI and dependencies
Open HubSpot and copy a personal access key
Paste the key in the terminal from the correct portal
“Starter theme created successfully“
cd into the correct directory (the one containing hsproject.json, package.json, etc.)
hs project upload
The project is created on HubSpot (authentication succeeds)
Build & deploy successfully
Go to src/theme/my-theme/package.json and add --ssl to the start script → becomes:
hs-cms-dev-server . --ssl
Upload the project again
In HubSpot → Website pages → create a new public page using the starter theme template
Enter name & title (leave the page public)
Publish the page
Visiting the live page works
Start the local dev server with npm run start from the project root (the directory with hsproject.json)
Server starts with no errors
Local template rendering works
Add hslocal.net:3000 to the URL of the live page
Result: blank page with HTML comment “Missing template…”

Would you be able to run a test on your side following exactly these same steps and check whether you also encounter the issue?

If not, could you please share your exact workflow/steps so I can replicate the setup you’re using that avoids this problem? Having a working reference would help a lot in understanding where the discrepancy may be.

Thanks!

Re: Problem while proxying public and private pages (CMS React)

sylvain_tirreau — Sun, 16 Nov 2025 18:53:16 GMT

Hi @FPConnect ,

Okay. There's an error in the theme-hsmeta.json file generated by the package: the variable "uid" contains "theme" when it should contain (given the generated files) "my-theme".

So, between steps 9 and 10, and in any case *before uploading* the project, you need to change the uid of theme-hsmeta.json and replace "theme" with "my-theme".

With this, my project is visible in "localhost:3000" and if I add "hslocal.net:3000" to my domain name followed by the page slug, it appears correctly in the browser.

@BérangèreL , are you reporting this to the developers, or do we need to submit it via the developer contact form? I think it's enough to just change "theme" to "my-theme" in the uid variable of the theme-hsmeta.json file.

Best

Re: Problem while proxying public and private pages (CMS React)

BérangèreL — Mon, 17 Nov 2025 09:07:46 GMT

Hi @sylvain_tirreau, and thank you so much for your help!

I’ve submitted the feedback on your behalf via the form 🤗

If you’d like to share feedback directly in the future, please feel free to do so via the HubSpot Developer Feedback Form.

Thanks again, and I hope you have a great day!
Bérangère

Re: Problem while proxying public and private pages (CMS React)

FPConnect — Mon, 17 Nov 2025 11:04:37 GMT

Thanks @sylvain_tirreau!
Updating the uid in theme-hsmeta.json to match my-theme actually fixed the issue with public pages - the proxy now works correctly there.

For private pages, though, I’m still running into the same problem: even if I log in on the live page first and then add hslocal.net:3000 to the domain, the proxied page keeps redirecting me back to the login screen.

For the moment I can work around it by manually copying the cookies from the live page to the local one, and that seems to let the page load.
But the native authentication flow still doesn't behave as expected.

Thanks again for the help - this was definitely a step forward.

Re: Problem while proxying public and private pages (CMS React)

sylvain_tirreau — Mon, 17 Nov 2025 11:55:25 GMT

It seems logical that it would break, since the cookies are set for a domain name that will change to "hslocal.net" when you modify the URL. But the documentation clearly states that this has no impact: "To view your local changes on a proxied membership page, first visit the page and log in with the configured method. Once authenticated, add hslocal.net:3000 or localhost:3000 to the root domain, just as you would with proxying a public page." (https://developers.hubspot.com/docs/cms/reference/react/local-development#proxying-private-pages)

If I were you, I would also report this issue on the developer feedback form: https://developers.hubspot.com/feedback

Re: Problem while proxying public and private pages (CMS React)

MFall13 — Sun, 25 Jan 2026 00:18:54 GMT

@FPConnect did you find a solution aside from copying the cookies for the private page proxy issue?

Re: Problem while proxying public and private pages (CMS React)

FPConnect — Mon, 26 Jan 2026 08:29:56 GMT

Hi @MFall13, no, I wasn't able to find a solution.
I'm still copying manually the cookies from the online page (after I logged in) to the local one running with the proxy.

Re: Problem while proxying public and private pages (CMS React)

BérangèreL — Mon, 26 Jan 2026 11:42:27 GMT

Hi @FPConnect, thanks for getting back to us!

Hey @Anton, @MichaelMa do you have any tips to share with @FPConnect and @MFall13, please?

Thanks so much and have a great day!
Bérangère

Re: Problem while proxying public and private pages (CMS React)

BérangèreL — Thu, 05 Feb 2026 15:55:25 GMT

Hi @FPConnect, when looking into this for you I could see that for previewing private or membership pages locally, here’s what works best:

- Visit the live page and log in using your configured method.
- Once authenticated, add hslocal.net:3000 or localhost:3000 to the root domain.

A couple of things to keep in mind:

- The “Missing Template” error you’re seeing (with @PReview/...) likely points to a template path issue in the local proxy, which can happen with project-based templates.
- There was a recent security update in June 2025 for cms-dev-server version 1.0.33, and older versions are now deprecated. If you’re on 1.0.32 or below, you might see a 401 “INVALID_SIGNATURE” error. Updating is easy, just run: npm update @hubspot/cms-dev-server

If the automatic authentication isn’t working as expected, manually copying cookies is a common workaround.

For the best experience, I recommend:

- Making sure you’re using the latest @hubspot/cms-dev-server (1.0.33 or higher)
- Starting the dev server with the --ssl option for HTTPS support

It does seem like a bug though, so I'd suggest to report it to our Support Team so that they can take a look.

Feel free to reach out if you have more questions or need extra help!

Thanks,
Bérangère

This post was created with the assistance of AI tools