Troubleshooting

Start with the simplest checks first: confirm OBS is running, Beam is enabled, and the dock shows the linked account and stream.

Fastest isolation steps

1. Confirm the Beam dock is visible in OBS and shows Beam as enabled.
2. Confirm the dock shows the expected linked account and stream.
3. Check the Mac’s connection to ingest.beamnetworks.stream.
4. Copy the Beam diagnostics from the dock before restarting anything.

Stop means end

Once a broadcast is live, pressing Stop Streaming in OBS ends that Beam broadcast after its pending uploads drain. Brief network interruptions do not end it; leave OBS streaming while the plugin reconnects and backfills.

OBS plugin not appearing after install

The Beam dock doesn’t show up in OBS.

• Confirm that beam-obs.plugin is in ~/Library/Application Support/obs-studio/plugins/. The folder name is case-sensitive.
• macOS may have blocked the plugin. Open System Settings → Privacy & Security and look for a message about the plugin being blocked. Click Allow Anyway, then quit and relaunch OBS.
• Make sure you are running OBS 32.1 or later. Older versions may not load the plugin.
• Confirm you are on an Apple Silicon Mac. The current beta does not run on Intel Macs.

Beam dock shows as inactive or offline

The dock appears but shows a red or inactive status during streaming.

• Use Link with Portal again if the dock does not show a linked account and stream.
• Confirm Beam is enabled after linking. Successful portal approval enables full delivery automatically.
• Confirm your Mac has outbound internet access to ingest.beamnetworks.stream on port 443.

Upload failures or segments not being delivered

Beam is active but the dashboard isn’t showing delivery.

• Verify api_endpoint is reachable. In Terminal:

  curl https://ingest.beamnetworks.stream/health

  You should get a 200 OK response. If the command times out or returns an error, there is a network issue between your Mac and Beam’s ingest service.
• Re-link the portal if the dock reports an authentication problem.
• The plugin retries uploads automatically. A short retry period is normal on a flaky connection; persistent retries indicate an account, endpoint, or network issue.

Agent exits immediately (standalone agent users only)

The agent process exits right away with an error.

• Confirm the config file path is correct: beam-agent --config /full/path/to/agent.yaml
• Open the config file and check for any tab characters — YAML requires spaces for indentation, not tabs.
• Make sure stream_id and api_key are filled in. The agent will not start with placeholder values.

Segments not being detected (standalone agent users only)

The agent is running but not picking up OBS output.

• Confirm OBS is actually writing .ts segment files to the directory specified in hls_watch_dir in your agent.yaml.
• The agent expects 2-second segments. If OBS is configured for a different segment length, segments may be detected but fail validation.

Contact support

If none of the above resolves your issue, contact Beam support. When you reach out, it helps to include:

• The error message or dock status you’re seeing.
• Your OBS version and macOS version.
• Whether the issue is consistent or intermittent.
• What changed before the problem started (new macOS update, new OBS version, changed config, etc.).