Troubleshooting

The URL doesn't resolve

DNS hasn't propagated, or the record is wrong.

dig api.YOUR_DOMAIN +short      # should return your edge's IP

• For self-host, the Cloudflare A record must be DNS only (gray cloud), not proxied — a proxied record makes Cloudflare terminate TLS and breaks Beamd's certs.
• Fresh records can take a few minutes (occasionally up to 24h for nameserver changes). Wait and retry.

"Your connection is not private" / cert errors

Either the certificate isn't issued yet, or the host doesn't match the wildcard.

• Not issued yet: on self-host, re-run beamd provision-dev (or add-developer) and watch the edge logs for ACME wildcard issued.
• Host doesn't match: the cert is exactly one DNS label deep — *.YOUR_DOMAIN covers api.YOUR_DOMAIN but not deep.nested.YOUR_DOMAIN. Use a single-label name (see Naming).

ACME issuance fails (self-host)

• unauthorized / forbidden: the Cloudflare token lacks Zone:DNS:Edit or isn't scoped to your zone. Recreate it and verify with the token-verify curl in the Setup walkthrough.
• DNS lookup-style errors: DNS hasn't propagated, or your host's resolver is flaky — pin 1.1.1.1 / 8.8.8.8 (the bundled compose file does). Wait and retry.

The framework rejects the tunnel host

Dev servers like Vite and Next reject requests for unknown hosts ("Blocked request. This host is not allowed."). Use beamd run, which injects the allowed-host env automatically:

beamd run -- npm run dev

If you're using beamd open against an already-running server, add the tunnel domain to your framework's allowed-hosts config. See Wrap a dev server.

beamd open hangs or says "no client connected"

The background agent holds the client→edge connection; if it can't reach the edge, open blocks. Check the agent log:

cat ~/.beamd/agent.log

Confirm the edge is reachable (curl -k https://YOUR_DOMAIN/healthz) and that your account points at the right server (beamd whoami).

"no route for host …"

You're hitting a name that isn't currently registered. List what's live:

beamd list

name_taken / over_limit

• name_taken: another tunnel already uses that name on the edge — pick a different --as, or beamd close the old one.
• over_limit: you've hit max_tunnels_per_token (default 25). Close tunnels you no longer need. See Limits & quotas.

Where the logs are

Still stuck? Open an issue on the repo.