Troubleshooting

Start with the simplest checks first: confirm OBS is running and Beam is enabled in the dock, check that your API key is correct, then work through the steps below.

Fastest isolation steps

1. Confirm the Beam dock is visible in OBS and shows Beam as enabled.
2. Confirm your API key in the Beam config file matches what’s shown in the Beam dashboard under Settings → API Keys.
3. Try stopping and restarting the OBS stream.
4. Check whether the issue is reproducible or was a one-off.

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 30 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.

• Check that runtime_mode is set to full in ~/Library/Application Support/Beam/obs-plugin.json. If it’s missing or set to anything else, Beam runs in a safe no-upload mode.
• Verify your API key is correct and has not expired. Generate a new key in the Beam dashboard if unsure.
• 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.
• Check that your API key in the config file is correct.
• The agent retries uploads automatically — check the Beam dock log area for retry messages. A short retry period (under 30 seconds) is normal on a flaky connection; persistent retries indicate an auth or endpoint 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.).