Hyperbeam Not Working? Fix the Embed Before You Rebuild

Which Hyperbeam Is Failing — and Why It Stops

A hyperbeam not working report almost always lands in one of three layers: the embed in your frontend, the network between your server and the API, or the Erlang node and Compute Unit behind HyperBEAM on Arweave. Two unrelated products share the name, so the fix list only helps once you know which layer you are looking at. Start from the symptom — a blank stream, a refused API call, a node that will not boot — and change one thing at a time.

The 60-Second Triage: Two Products, Two Fix Lists

Hyperbeam at hyperbeam.com is an API for embedding a virtual computer inside a web app: a REST API on your backend creates sessions, and an npm client on the frontend renders the stream with synced audio, video and multi-user control. HyperBEAM is an Erlang-based Arweave node you compile with rebar3 and pair with a Node.js Compute Unit started by npm start.

Most hyperbeam not working reports resolve the moment you confirm which product the failing request actually hits, because the two share a name and nothing else. Search results interleave both, which is why people chase an Erlang build error when their real problem is a missing play button.

If the embed concept itself is still fuzzy, the difference between a rendered remote browser and a local tab is explained in this piece on virtual browser in Chrome. Read it before you start changing code, because a container that was never sized correctly will keep looking like a server fault.

Symptom: The Embed Loads but the Stream Never Starts

The container renders, the JavaScript bundle runs, and then nothing. That pattern is client-side, and there are three usual causes.

The embed URL did not come from the REST API

If a hyperbeam not working report lands right after a deploy, a cached embed URL is the first suspect. Hyperbeam’s embed URL is issued per session by the REST API, and the client constructor expects that URL. If you cached one in a config file months ago, or hand-assembled it, the session is dead or was never valid. Create a fresh session on your server, hand the URL to the browser, and construct the client with it. Do not pass the API key to the frontend to skip this step.

The container is an iframe instead of a div

Hyperbeam’s own guidance is to pass a div to the constructor. An iframe gives you a nested document with its own stacking, sizing and event model, and the stream often renders at zero height or swallows pointer events. Hyperbeam also positions its embedding as the answer to X-Frame-Options refusals on third-party sites — you get the remote page inside the stream instead of framing the site directly, which is why a raw iframe fails where the embed works.

Autoplay is blocked until the user clicks

Browsers refuse to start media with audio without a user gesture, so the embed waits for a click instead of streaming. That is the browser’s autoplay policy, not a network fault. Wire the play control to the client’s start path, and in a kiosk or demo context put the button where a person can actually reach it. If your integration keeps the button out of reach and expects sound to play anyway, nothing renders.

The same false-negative pattern shows up whenever a hosted app loads in one environment but not another: check the console, then the network tab, then the session config. The ordered method in this cloud browser not working walkthrough applies to a Hyperbeam stream as well.

Symptom: The Stream Drops, Freezes or Refuses to Resize

Once pixels are flowing, the remaining failures live in the client SDK’s lifecycle. Three methods cover most of them.

Disconnects: call hb.reconnect()

Hyperbeam’s JavaScript client exposes hb.reconnect() for exactly the case where the virtual browser disconnects. That makes a visible reconnect control a supported debugging move, not a hack — it separates a transient transport drop from a session that no longer exists. If reconnect restores the stream, log the timing and look at your network path; if it fails, the session is gone and your backend needs to issue a new embed URL.

Resize throws RangeError: you hit the area cap

hb.resize() raises a RangeError when width times height exceeds hb.maxArea. Read hb.maxArea first, then clamp your dimensions before calling resize. A stream that “refuses to resize” on a large monitor is hitting a documented ceiling, and resizing in a loop without clamping turns one error into a console flood.

Teardown order: destroy before you remove the node

Always call hb.destroy() before removing the container from the page. It closes network connections and browser events that otherwise keep running after the element is gone. In a single-page app this can leave a socket open per navigation, and the symptom surfaces later as a stale session or a stream that will not start at all.

// Container must be a div, not an iframe.
const container = document.getElementById("beam");
const hb = new Hyperbeam(embedUrl, container, { adminToken });

// Manual reconnect for a dropped virtual browser.
document.getElementById("reconnect").addEventListener("click", () => {
  hb.reconnect();
});

// Tear down sockets and browser events before removing the element.
function closeBeam() {
  hb.destroy();
  container.remove();
}

// Clamp dimensions to the documented area cap before resizing.
function safeResize(w, h) {
  const scale = Math.min(1, Math.sqrt(hb.maxArea / (w * h)));
  hb.resize(Math.floor(w * scale), Math.floor(h * scale));
}

Symptom: API Calls Fail with CORS or Proxy Errors

CORS failures with Hyperbeam are a placement problem, not a permissions puzzle, and most hyperbeam not working reports that mention a console error start here. The REST API is meant to be called from your server, which holds the key; a browser-side fetch exposes the key and gets refused by the origin policy. Move the call to a backend route, return only the embed URL to the client, and allowlist Hyperbeam’s published IP ranges on any egress firewall. Make that change first — it clears the CORS class of failures without touching client code.

Proxies behave differently from what most people assume. The Hyperbeam FAQ says only HTTP traffic goes through the configured proxy and WebRTC traffic is excluded, so the proxy scheme — SOCKS, HTTP or HTTPS — makes no difference to that stream. If a test shows a local IP appearing through a webview, WebRTC is the likely path, not a broken proxy setting. Separately, Hyperbeam does not support proxy authentication over SOCKS because Chrome does not implement it; the documented alternative is an HTTPS proxy scheme. Desktop users hit the same wall, covered in detail in SOCKS5 proxy not working.

Symptom: The HyperBEAM Node Won’t Start

On the Arweave side, failures are build and boot problems. The official troubleshooting reference splits them into install, startup and integration problems, and it is worth reading in that order: HyperBEAM troubleshooting reference.

How Send.win Helps With Hyperbeam Not Working

Send.win is a browser profile manager for professionals and teams: every account gets its own isolated browser profile.

• Isolated profiles – separate cookies, storage and sessions per profile
• Fingerprint protection – each profile keeps its own consistent browser fingerprint, so profiles never share one browser identity
• Desktop app + cloud browser – native app for Windows, macOS and Linux, or run profiles in the cloud with no install
• Residential proxies included – on Pro and Team, with timezone and locale matched to the proxy
• Team sharing – share a signed-in profile with a teammate without sharing the password

Try the free cloud demo — no install — or download the desktop app. Paid plans start at $19/month, and your first card purchase is covered by a 7-day money-back guarantee (see pricing).

Erlang or Rebar3 will not compile

Compilation failures on a fresh machine are usually missing system libraries. Install libssl-dev, ncurses-dev, make, cmake, gcc and g++, then rebuild. On a constrained box you can configure with fewer options, for example --without-wx and --without-debugger, to drop the parts that need GUI dependencies. If the Rebar3 bootstrap itself fails, confirm which Erlang release you actually have with erl -eval 'erlang:display(erlang:system_info(otp_release)), halt().' and reset the repository to origin/master before retrying.

Port conflict, wallet file, missing dependency

A node that refuses to boot usually has one of three causes: the port is already held by another process, the wallet key file is missing or unreadable, or a dependency never installed. Erlang writes crash dumps that carry the real detail, so read the dump before you reinstall anything — the stack trace names the failing module. Check the port with your platform’s socket listing tool, and confirm the key file’s permissions let the same user that starts the node read it.

Confirm the Compute Unit before blaming the node

From the HyperBEAM machine, run curl http://localhost:6363. A response means the CU is alive and the problem sits in the node’s integration. Connection refused means the CU is the problem and the node is innocent. When the two components run on different machines, verify firewall rules between them and confirm the CU is bound to an interface the node can reach, not just loopback.

Symptom: The Compute Unit Crashes or Refuses to Start

For a CU that will not come up with npm start, check four things in order: node -v against the required version, npm i to confirm dependencies installed cleanly, the wallet file’s format, and that .env contains every setting the process reads. A truncated JSON wallet or a missing environment variable produces a start failure that looks like a code bug.

Out-of-memory crashes are a tuning problem, not a capacity problem. The Compute Unit is tuned with the PROCESS_WASM_MEMORY_MAX_LIMIT environment variable, and garbage collection is enabled through a GC_INTERVAL_MS value — if that interval is unset, memory climbs until the process dies. Lower the WASM memory ceiling to the workload you actually run, set a GC interval short enough to reclaim before the ceiling is reached, then retest with the request that killed it rather than a trivial one.

Is hyperbeam.com Down, or Is It Your Setup?

Before you file a hyperbeam not working ticket, separate an outage from a local fault. Independent uptime checkers last saw hyperbeam.com responding — 30 ms from a San Francisco location on 2026-05-10, and 10 ms on 2025-09-12, both marked up. That is evidence the domain is alive, and it is not evidence of anything about your session: only two sample points exist, which supports no outage-rate claim at all. Test from a second network, then check whether the failure follows your account, your browser or your machine.

How to Stop the Same Failure Coming Back

Recurring breakage usually comes from debugging in a contaminated environment. When you build and test an embed in the same browser session you use for everything else, a stale cookie, a cached bundle or a service worker from an older build will fake a server fault. You reload, see the same broken screen, and conclude the backend is down when the browser is serving yesterday’s JavaScript.

Isolate the test environment the same way you isolate the fix. A browser profile manager gives each project its own cookies, storage, sessions, fingerprint settings and proxy, so a test build never inherits state from a client workspace or a previous experiment. Send.win runs those profiles two ways: the Sendwin Browser desktop app for Windows 10/11, macOS 12+ and Linux, and a cloud browser that runs profiles on an EU server in Helsinki from any device. For a QA loop where one person tests as a logged-in user in one region and an anonymous visitor in another, that separation is what makes results repeatable — a broader treatment is in this browser isolation for remote work guide.

Two habits keep the rest stable. Pin the client SDK version and read the changelog before upgrading, since reconnect and resize behaviour is documented per release. And keep a one-page runbook with the ladder — site status, console, embed URL, container, SDK lifecycle, node port, CU memory — so nobody starts in the middle and nobody opens a ticket that says only “it broke again”.

Frequently Asked Questions

Why is my Hyperbeam virtual browser not loading?

Check three things in order: whether the embed URL came from a fresh REST API session, whether the constructor received a div rather than an iframe, and whether a user gesture started playback. If all three are correct, open the browser console — a failed session fetch or a CORS refusal will name the failing layer immediately.

Why does Hyperbeam show a play button instead of autoplaying?

Browsers block media with audio until the user interacts with the page. The play button is the required gesture, not a fault. Keep it visible and reachable, and the stream starts normally; remove it from reach and nothing renders.

How do I fix Hyperbeam CORS errors on API requests?

Move the call to your server. The REST API should be reached from your backend, which holds the key and creates the session, then returns only the embed URL to the client. Allowlist Hyperbeam’s published IP ranges on your egress firewall so server-side requests are not dropped.

Does Hyperbeam support SOCKS proxy authentication?

No. Hyperbeam’s documentation states that proxy authentication over SOCKS is unsupported because Chrome does not implement it, and recommends an HTTPS proxy scheme instead. Note also that only HTTP traffic goes through the proxy — WebRTC is excluded, so a local IP appearing on a webview usually points at WebRTC rather than a bad proxy setting.

Why won’t my HyperBEAM node start?

The three usual causes are a port conflict, a missing or unreadable wallet key file, and an uninstalled dependency. Erlang crash dumps carry the specific failure, so read the dump before reinstalling. To rule the Compute Unit out, run curl http://localhost:6363 from the node’s machine.

How do I fix out-of-memory errors in the HyperBEAM Compute Unit?

Set PROCESS_WASM_MEMORY_MAX_LIMIT to a ceiling that matches your real workload and set GC_INTERVAL_MS so garbage collection actually runs. Then retest with the request that triggered the crash. If npm start also fails, verify node -v, run npm i, and confirm the wallet file and .env are complete.

Is hyperbeam.com down right now?

Uptime checkers last recorded hyperbeam.com responding in tens of milliseconds, in checks from 2025 and 2026, so the domain is not shut down. Those are only two samples and say nothing about your session. Test from a second network before assuming an outage, because local network and session problems are far more common.

How do I reconnect a Hyperbeam embed that dropped?

Call hb.reconnect(), which exists for exactly this case. If the stream returns, the drop was transport-level and worth logging. If reconnect fails, the session is gone and your backend needs to create a new one and hand over a fresh embed URL.

Related Products & Resources

• Download
• Demo Browser
• Pricing
• Fingerprint Checker
• Canvas Fingerprint Test