Problem while proxying public and private pages (CMS React)

[FPConnect]

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:

1. Open the page online and log in.

2. 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:

<!-- Missing Template at Path: '@preview/5159ac59-82d0-4cdd-86e6-0488f964dba4/@projects/.../theme/templates/dashboard.hubl.html' -->

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!

[sylvain_tirreau · Accepted solution]

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

[nickdeckerdevs1]

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.

[FPConnect]

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.

[BérangèreL]

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.

[FPConnect]

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:

1. I updated all packages to the latest versions.
2. I created a brand-new theme using the official CMS React starter (the boilerplate provided by HubSpot).

3. 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.

[BérangèreL]

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

[FPConnect]

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.

[sylvain_tirreau]

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".

[FPConnect]

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:

1. npx @hubspot/create-cms-theme@latest

2. Choose a theme name

3. Select TypeScript: yes

4. Choose directory

5. Automatic installation of CLI and dependencies

6. Open HubSpot and copy a personal access key

7. Paste the key in the terminal from the correct portal

8. “Starter theme created successfully“

9. cd into the correct directory (the one containing hsproject.json, package.json, etc.)

10. hs project upload

11. The project is created on HubSpot (authentication succeeds)

12. Build & deploy successfully

13. Go to src/theme/my-theme/package.json and add --ssl to the start script → becomes:
    hs-cms-dev-server . --ssl

14. Upload the project again

15. In HubSpot → Website pages → create a new public page using the starter theme template

16. Enter name & title (leave the page public)

17. Publish the page

18. Visiting the live page works

19. Start the local dev server with npm run start from the project root (the directory with hsproject.json)

20. Server starts with no errors

21. Local template rendering works

22. Add hslocal.net:3000 to the URL of the live page

23. 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!

[sylvain_tirreau · Accepted solution]

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

[FPConnect]

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.

[sylvain_tirreau · Accepted solution]

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

[BérangèreL]

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

[BérangèreL]

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.

[FPConnect]

Hi @BérangèreL 

The issues are actually two separate ones:

1. 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.

2. 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!

[BérangèreL]

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