Issues with shopify.web.toml background role

Topic summary

Adding a background process via a second shopify.web.toml (roles: [“background”]) caused the app to fail loading in the test store, despite both dev processes starting. The error shown was: “Error forwarding web request: AggregateError.”

Setup details: root shopify.web.toml with roles [“frontend”, “backend”] running Remix dev; a new folder containing shopify.web.toml named “pubsub” with dev command “node pubsub.js”.

Status/outcome: Identified as a Shopify CLI issue and fixed in CLI version 3.66.0. A GitHub issue (4309) confirms the fix.

Resolution: Update the Shopify CLI to v3.66.0 or later. No additional workarounds were provided.

State: Resolved by upgrading the CLI; no remaining unanswered technical questions in the thread.

Summarized with AI on December 21. AI used: gpt-5.

I am using Shopify’s recommended remix app.
In the root directory I have a shopify.web.toml file (the default)

name = "app"
roles = ["frontend", "backend"]
webhooks_path = "/webhooks"

[commands]
dev = "npm exec remix dev"

[hmr_server]
http_paths = ["/ping"]

When i run npm run dev this works perfectly and I can access the app in my test store.

Now I want to add a background process using the “background” role talked about in this link: https://shopify.dev/docs/apps/tools/cli/structure#background-process

I made a folder in the root directory and I have a js file and another shopify.web.toml file with this in it

name = "pubsub"
roles = ["background"]

[commands]
dev = "node pubsub.js"

When I run npm run dev in the root directory, both processes startup (i can see output from each process in the terminal) however when I try to access the app within my test shop it won’t load and I get this error:
“Error forwarding web request: AggregateError”

I’m not entirely sure why and I don’t know how making a background process with another shopify.web.toml is causing the error when it works when I don’t have the second process running.

1 Like

Hi @bpaul18 , have you find any solution for this issue ?

This has been fixed in the latest version of the CLI (3.66.0).

https://github.com/Shopify/cli/issues/4309