Skip to main content
This page covers common issues you may encounter when using Substrate and how to resolve them. If your issue is not listed here, reach out on the Bedrock Dynamics Discord.
Substrate uses Docker to run PX4 and Gazebo SITL simulations. If a simulation fails to launch:
  1. Verify Docker is running. Open a terminal and run docker ps. If the command fails, start Docker Desktop (macOS/Windows) or the Docker daemon (Linux).
  2. Check available disk space. Simulation images are 2—4 GB each. If your disk is full, Docker cannot pull or run containers.
  3. First launch is slow. If this is the first time launching a particular simulation configuration, Substrate needs to pull the Docker image. This can take several minutes depending on your internet connection. Progress is displayed in the output panel.
  4. Port conflicts. If another application is using MAVLink ports (14540, 14550) or the Gazebo transport ports, the simulation container may fail to start. Stop any conflicting processes and try again. 
# Check if Docker is running
docker ps

# Check for port conflicts
lsof -i :14550
The 3D Viewer requires a GPU that supports Vulkan (Windows/Linux) or Metal (macOS).On Linux:
  • Install the Vulkan runtime and tools: sudo apt install vulkan-tools mesa-vulkan-drivers
  • Verify Vulkan support: run vulkaninfo and confirm at least one GPU is listed.
  • Update your GPU drivers to the latest version from your vendor (NVIDIA, AMD, or Intel).
On macOS:
  • Metal is supported on all Macs from 2012 and later. If you see a black screen, ensure macOS is updated to at least version 12 (Monterey).
On Windows:
  • Update your GPU drivers from the manufacturer’s website. Vulkan support is included in modern NVIDIA, AMD, and Intel drivers.
  • If Vulkan is unavailable, Substrate falls back to DirectX 12.
If the problem persists after updating drivers, check the Substrate log file for rendering errors. The log is located at ~/.local/share/substrate/log (Linux), ~/Library/Logs/substrate/ (macOS), or %APPDATA%\substrate\log (Windows).
The AI Assistant requires an active internet connection and an authenticated Substrate account.
  1. Check sign-in status. Click the avatar in the top-right corner of the window. If you are not signed in, click “Sign In” and complete the authentication flow.
  2. Check the connection indicator. A red indicator next to the AI panel header means the WebSocket connection to the AI backend is down. Verify your internet connection and try again.
  3. Free plan includes AI access. No upgrade is required to use the AI Assistant. If you are signed in and connected but still not receiving responses, the backend may be experiencing temporary load. Wait a moment and retry.
  4. Firewall or proxy issues. If you are behind a corporate firewall, ensure that outbound WebSocket connections to *.bedrockdynamics.studio on port 443 are allowed.
This is expected. PX4 + Gazebo simulation stacks include:
  • A full physics simulator (Gazebo Harmonic)
  • Sensor models (IMU, GPS, magnetometer, barometer, camera)
  • Autopilot firmware (PX4 or ArduPilot)
  • The simulation bridge (substrate-sim-bridge)
  • Runtime dependencies (ROS 2 libraries, Protobuf, system packages)
A typical image is 2—4 GB compressed. After pulling, Docker stores the image layers on disk.To reclaim space:
# Remove unused Docker images
docker image prune

# Remove all Substrate simulation images
docker images | grep substrate | awk '{print $3}' | xargs docker rmi
Substrate will re-pull any required images automatically on the next simulation launch.
After launching a PX4 SITL simulation, the readiness indicators (GPS, compass, EKF, gyroscope) transition from red to yellow to green as each subsystem initializes. It is normal for this process to take 10—15 seconds.If indicators remain yellow after 30 seconds:
  • EKF convergence. The Extended Kalman Filter needs consistent sensor data to converge. If GPS or compass indicators are still yellow, the EKF cannot complete initialization. Check the simulation output panel for EKF-related warnings.
  • Sensor spawning. Ensure the simulation is using PX4 spawn mode (PX4_MODEL=x500), not attach mode. Attach mode skips sensor spawning, which means the EKF never receives data and cannot converge.
  • World file issues. Some custom Gazebo worlds may not include the required sensor plugins (GPS, magnetometer). Verify that your world file includes the necessary sensor system plugins.
Never set PX4_GZ_MODEL_NAME in the Docker environment. This enables attach mode, which skips sensor spawning and causes the EKF to stall at an uninitialized state.
Substrate connects to robots and external systems via Foxglove WebSocket.
  1. Verify the bridge is running on the robot. SSH into the robot and confirm the Foxglove WebSocket bridge process is active: 
    # For ROS 2 Foxglove Bridge
ros2 launch foxglove_bridge foxglove_bridge_launch.xml
  2. Check the port. The default Foxglove Bridge port is 8765. Confirm this in the bridge’s launch configuration and in the Substrate connection dialog.
  3. Network connectivity. Ensure the robot is reachable from your development machine. Test with: 
    # Test WebSocket connectivity
curl -v http://<robot-ip>:8765
  4. Firewall rules. Both the robot and your development machine must allow traffic on the bridge port. On Linux robots, check ufw or iptables rules.
  5. VPN or SSH tunnel. If the robot is on a different network, you may need a VPN or SSH tunnel: 
    # SSH tunnel for Foxglove Bridge
ssh -L 8765:localhost:8765 user@robot-ip
    Then connect to ws://localhost:8765 in Substrate.
If the simulation panel shows “No simulation stacks available”:
  1. Check Docker is running. Run docker ps in a terminal. If the command fails, start Docker Desktop (macOS/Windows) or the Docker daemon (Linux).
  2. Check network connectivity. Substrate queries Docker Hub to discover available simulation stacks. Verify you can reach the registry: 
    ping registry.hub.docker.com
  3. Pull image manually. If the registry is unreachable, you can pull a simulation image manually and Substrate will detect it: 
    docker pull bedrockdynamics/substrate-sim:px4-gazebo-humble
After pulling, restart Substrate or refresh the simulation panel to see the locally available stack.
Symptom: Warning message “Docker Hub rate limit exceeded. Retry after 60m”Cause: Docker Hub limits anonymous users to 100 image pulls per 6 hours. If you exceed this limit, subsequent pull requests are blocked until the limit resets.Solutions:
  1. Wait for the rate limit to reset. The warning message shows when the limit will reset (typically 1-6 hours from when you hit the limit).
  2. Authenticate with Docker Hub. Create a free Docker Hub account and log in: 
    docker login
    Authenticated users have a higher rate limit (200 pulls per 6 hours for free accounts, unlimited for paid accounts).
  3. Use locally cached images. If you have already pulled the image once, Substrate will continue to work using the local copy. The IDE automatically falls back to local images when the registry is unavailable.
Symptom: Warning message “Showing local images only” or “Registry unavailable”Behavior: When the Docker Hub registry is unreachable (due to network issues, rate limits, or being offline), Substrate automatically falls back to showing only simulation stacks that are already pulled locally.Note: This is expected behavior and allows you to continue working offline. You can still launch any simulation stack that appears in the list. To see the full list of available stacks, restore network connectivity and restart Substrate.
Symptom: A simulation stack displays a generic name (like “px4-gazebo-humble”) instead of a formatted name (like “PX4 + Gazebo (Humble)”)Cause: The Docker image was built before OCI labels were added to the build process. Older images lack the metadata Substrate uses to format display names.Solution: Pull the latest version of the image:
docker pull bedrockdynamics/substrate-sim:px4-gazebo-humble
After pulling the updated image, the formatted display name will appear in the simulation panel.

​
Diagnostic Information

If you need to file a bug report, include the following:
  • Substrate version: Found in Help > About.
  • Operating system and version.
  • GPU model and driver version: Run vulkaninfo --summary (Linux/Windows) or check About This Mac > More Info (macOS).
  • Log file: Located at the paths listed in the “3D Viewer shows a black screen” section above.
  • Docker version: Run docker --version.