Fix BigBlueButton Greenlight Dashboard 500 Internal Server Error

A 500 Internal Server Error means a server-side request failed; it does not identify which component failed. For a BigBlueButton Greenlight dashboard, start by finding the failing request in the Greenlight application logs. BigBlueButton’s troubleshooting guide says a 500 is most likely a Greenlight error. The exception is useful: if only some computers on a local network see it and the log reports an “Unsafe Host Error,” a browser proxy setting may be involved.

Greenlight v3 is the current documented release and uses a different deployment layout from the older v2. This guide helps you identify your version, collect the right evidence, and check common causes in a safe order. It assumes a Docker-based Greenlight deployment. Use commands as a server administrator and adapt the container name and path if your installation differs.

Understand which component is returning 500

Greenlight is the web application used to sign in, manage rooms, and start BigBlueButton meetings. A reverse proxy such as Nginx receives browser requests and forwards them to Greenlight. Greenlight then communicates with BigBlueButton’s API and relies on services such as PostgreSQL and Redis. A 500 can originate in Greenlight, a proxy, or a dependency; restarting BigBlueButton media services will not fix a database or application exception.

First note what action triggers the error: opening the dashboard, signing in, loading a room list, or starting a meeting. Record the URL path, approximate time, whether every user is affected, and any recent change such as an upgrade, DNS edit, proxy change, or credential rotation. If the homepage loads but one action returns 500, that narrows the request to investigate.

Prepare before changing anything

• Confirm whether the image is bigbluebutton/greenlight:v3, a v2 image, or a custom build. Do not apply v2 instructions to v3.
• Keep a copy of the relevant Docker Compose file and environment file in a secure location before editing them. They contain credentials.
• Record the error timestamp and inspect only a short log window around it. Redact passwords, access tokens, API secrets, email addresses, and private meeting links before sharing logs.
• Do not run docker compose down -v, remove database volumes, or delete Greenlight storage to “reset” the dashboard. Those actions can destroy accounts, settings, or uploaded assets.

Step 1: Check the running containers and capture the exception

On the Docker host, list Greenlight-related containers and their images and status:

sudo docker ps -a --filter name=greenlight \
  --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}'

For the standard Greenlight v3 installation, the application container is commonly named greenlight-v3. Read its recent output around the time of failure:

sudo docker logs --since=15m --tail=200 greenlight-v3

If your installation uses Compose, run docker compose ps and docker compose logs --since=15m --tail=200 from the directory containing its Compose file. The BigBlueButton installation may keep v3 files under ~/greenlight-v3; standalone installs can differ. Use the actual location and container names reported by your host. For older v2 installs, check the mounted Rails log, commonly log/production.log inside the Greenlight installation directory, or inspect /usr/src/app/log/production.log in the container if it is not mounted.

Look for the first exception at the time of the failed request, not just the final 500 response. Database connection errors, Redis errors, API request failures, certificate validation errors, and Rails exceptions point to different fixes. If the container has exited, its logs may still be available through docker logs.

Step 2: Check Greenlight’s connection to BigBlueButton

When the dashboard fails while loading rooms or starting a meeting, verify the BigBlueButton URL and shared secret used by Greenlight. For v3, the environment file includes BIGBLUEBUTTON_ENDPOINT and BIGBLUEBUTTON_SECRET. The endpoint must be the API URL for your deployment, not a guessed host or a browser-only meeting URL. If you use a load balancer such as Scalelite, use the endpoint and credentials provided for that setup.

On the BigBlueButton server, sudo bbb-conf --secret displays the configured URL and secret. Compare them privately with Greenlight’s values. Do not paste the secret into a ticket, shell transcript, or public chat. A stale secret after a reinstall or credential rotation can cause API calls to fail even while the dashboard container is healthy.

Also run sudo bbb-conf --check on the BigBlueButton host. It checks BigBlueButton services and common configuration problems; it does not replace inspecting Greenlight logs. If Greenlight is on a separate standalone host, this command belongs on the BBB server where bbb-conf is installed.

Step 3: Check the database, Redis, and recent upgrades

Greenlight v3’s sample environment defines database and cache connections with DATABASE_URL and REDIS_URL. Confirm that the PostgreSQL and Redis containers are running and that the values in the application environment match the Compose service names, ports, database name, and credentials. A healthy-looking Greenlight container can still return 500 if it cannot reach one of these dependencies.

If the error began after an upgrade, compare the deployed image tag, Compose file, and environment file with the release procedure you followed. Avoid pulling an arbitrary image or manually changing the database schema while diagnosing production. Back up the database first, then use the documented Greenlight upgrade process for your installation. Check disk space as well: a full volume can prevent PostgreSQL writes, log writes, or asset storage updates.

Step 4: Check proxy, hostname, and subpath settings

If the error appears only through the public hostname, check the path from the browser through the reverse proxy to Greenlight. Confirm that the proxy forwards to the correct internal port and preserves the expected host and protocol headers. Test the proxy configuration before reloading Nginx with sudo nginx -t, then inspect the proxy error log at the matching timestamp.

Greenlight v3 expects to run at the root path by default. If it is published under a path such as /gl, its RELATIVE_URL_ROOT and reverse-proxy rules must agree. The official installation guide says a relative URL root change requires an upgrade/reconfiguration through the install procedure; setting a shell variable alone does not fix a mismatched existing deployment. A mismatch more often causes broken redirects or assets, but a failed proxied request can expose itself as an application error.

BigBlueButton documents a specific LAN case: if only some computers behind a proxy get the 500 and the Greenlight log contains Error::Unsafe Host Error, check that Windows is set to bypass the proxy for local or intranet addresses. This is a client network path issue, not a reason to disable host validation globally.

Step 5: Review authentication and email changes

If the 500 happens during sign-in, check recent changes to OpenID Connect settings, callback URLs, or the identity provider. Greenlight v3 uses values such as OPENID_CONNECT_ISSUER, OPENID_CONNECT_CLIENT_ID, and OPENID_CONNECT_REDIRECT when external authentication is configured. Confirm the redirect URL matches the public Greenlight URL, including any configured subpath, and review both Greenlight and identity-provider logs for the same timestamp.

Greenlight’s v3 documentation says email is required for basic platform features. If the dashboard fails during an invitation, sign-up, password reset, or another email action, check SMTP connectivity and credentials, TLS settings, and the application log. Keep SMTP secrets private. A failure limited to mail-related actions is a clue to investigate mail configuration before changing BigBlueButton API credentials.

Restart only after identifying the likely cause

Once you correct a confirmed environment or proxy issue, restart the affected Greenlight service using the Compose file for that installation. For example, from the v3 installation directory:

cd ~/greenlight-v3
sudo docker compose ps
sudo docker compose restart greenlight-v3

Compose service names can differ from container names. If the restart command says the service is unknown, inspect docker compose config --services and restart the listed Greenlight service, or use the deployment’s documented update command. Avoid restarting PostgreSQL or removing volumes unless logs show a dependency problem and you have a recovery plan.

Verify the fix and know when to escalate

Repeat the exact action that previously failed, then check the response in the browser and the Greenlight log at the new timestamp. Confirm that users can load the dashboard and, if the original failure involved a meeting, start a test meeting. If bbb-conf --check passes but the application still returns 500, that points the investigation back toward Greenlight, its dependencies, or the proxy.

If it remains unresolved, provide the Greenlight version or image tag, deployment type, the affected URL path, time of failure, relevant redacted exception, container status, and recent changes. Do not share full environment files, API secrets, database passwords, user session cookies, or unredacted logs.

Use the BigBlueButton troubleshooting guide for the official interpretation of 500 errors and Greenlight v3 installation and configuration documentation for the current v3 deployment model. The project’s Greenlight v3 sample environment file lists supported environment variables. Greenlight v2 and v3 differ, so use documentation that matches your deployed version.