Troubleshooting

Short fixes for the problems people run into most.

No flag appears

Check that the URL had ?stagepass=<name>.sp with a valid name and that the loader is in the Head Code of the published site. Sessions end after 12 hours by default, so add the parameter again. Run stagepass doctor to check the server, DNS, certificates and links in one go.

The card asks for local network access

Chrome blocks requests from the public site to your Mac until you allow local network access. Allow it in the prompt or in the site settings of Chrome, then reload. The session card shows the hint.

Local files return errors or do not load

Run stagepass start and check that the folder is linked with stagepass link. Open https://<name>.sp/<path> directly to test the file. Read ~/.stagepass/server.log or start with -v for details. If the browser does not trust the certificate, run stagepass certs check and stagepass certs trust.

CORS error in the console

Tags with type="module" or crossorigin and files loaded with fetch need CORS. Allow your live and staging hosts with stagepass link --origin www.example.com --origin my-site.webflow.io. Use exact hosts. *.webflow.io would allow every Webflow site and prints a warning.

The card says Local server sends no CORS header when a swapped file was loaded again without crossorigin. It works, but error details are limited. Add your host with stagepass link --origin.

A file returns 404

Paths with a segment that starts with a dot, node_modules and key, certificate, database and log files are always blocked. Move build output to a normal folder.

Port 443 is in use

stagepass start detects the conflict and offers to stop the other server, for example nginx, Valet or Apache. Answer no if you want to stop it yourself.

.sp names do not resolve

Run stagepass setup again. It writes /etc/resolver/sp and restarts Dnsmasq.

link rejects my domain or changes it

Domains must be DNS safe and end in .sp. Without an argument, the folder name is turned into a valid name. Use the printed domain.

Console logs disappeared or appear in production

Since 2.0 only sp.log, sp.warn and sp.error are quiet without a session. Your own console calls are untouched unless you set data-stagepass-mute-console="true".

Visitors still get an old file

Set data-stagepass-version on the loader tag or data-stagepass-v on the asset and bump it with every deploy.

Still stuck? Open an issue with the output of stagepass doctor --json and stagepass start -v.