Step-by-step guide to diagnosing and resolving Docker networking problems on TrueNAS Scale, including bridge configs, host networking, and inter-container communication.
Docker networking on TrueNAS Scale can be a source of frustration for many homelab enthusiasts. Whether your containers can't reach the internet, you lose access to the TrueNAS web interface after a network change, or your apps can't talk to each other — networking issues are among the most common problems when running Docker on TrueNAS. This guide covers the most frequent TrueNAS Docker networking issues and shows you how to fix them using verified methods from the TrueNAS community and official documentation.
TrueNAS Scale uses Docker under the hood to run containerized applications (called "Apps" in the TrueNAS UI). Each app you install from the catalog or deploy via custom YAML is essentially a Docker Compose project. By default, each app gets its own isolated network, which means apps cannot communicate with each other unless you explicitly configure inter-container networking.
The key networking modes available for TrueNAS Docker containers include:
Before troubleshooting, ensure you have:
One of the most critical problems is losing all network access to your TrueNAS system after changing a Docker container's network mode. This can happen when you enable Docker host networking in the GUI or modify network bridge settings.
What happens: When you enable host networking or change the Docker network configuration, Docker can modify iptables rules that may block traffic to the TrueNAS management interface.
How to fix it: According to the TrueNAS Community Forums, you may need to knock out the Docker compose and container configuration files located in the system directories. Access your TrueNAS via direct console (keyboard and monitor or IPMI), then stop the affected Docker containers and remove or rename the configuration files that caused the conflict. After a reboot, the system should revert to its previous networking state.
Prevention tip: Always use the Test Changes feature available on the Network screen in TrueNAS when modifying network interfaces. After saving changes, TrueNAS displays unapplied changes above the Interfaces widget. Click Test Changes, wait for the interface to initialize, and confirm you can still access the web UI before clicking Save Changes.
A very common scenario: your Docker containers start successfully, but they cannot connect to external services (package registries, APIs, or the wider internet).
Root cause: Docker containers on a bridge network use Network Address Translation (NAT) through the host's IP to reach the internet. If the iptables rules for masquerading are missing, misconfigured, or overridden, containers will lose external connectivity.
Solution: Create a custom Docker bridge network and assign your containers to it. As noted in Reddit discussions about this issue, creating a custom docker network, bridging it to your ethernet interface, then assigning your container to that network often resolves connectivity problems.
To create a custom Docker network via SSH:
sudo docker network create --driver=bridge --subnet=192.168.238.0/24 --gateway=192.168.238.1 your_custom_bridgeThen reference this network in your app's YAML configuration:
networks:
- your_custom_bridgeIf you run multiple apps (for example, MariaDB and Home Assistant) and they cannot talk to each other, the issue is that each TrueNAS app runs as its own isolated Docker Compose project with its own default bridge network.
Fix for TrueNAS 24.10 (Electric Eel) and newer: Inter-app communication was implemented starting with TrueNAS Scale 24.10 Electric Eel. To use it:
1. When editing or installing an app, look for the option to add additional Docker networks in the networking section of the app configuration.
2. If you are using custom apps via YAML (Docker Compose), you can directly edit the compose configuration and add additional networks under the networks key:
services:
my_app:
# ... your service config
networks:
- shared_network
networks:
shared_network:
external: true
name: your_custom_bridgeNote: If TrueNAS does not yet support custom Docker networks for GUI-installed apps in your version, community-built tools like tjhorner/dragonify can add TrueNAS app containers to custom docker networks. Check the compatibility with your TrueNAS version before using third-party tools.
A tricky issue arises when you try to create a Linux bridge on TrueNAS Scale for VMs or containers. Sometimes, after creating a bridge interface and rebooting, the TrueNAS host can no longer route traffic to the internet.
The fix: According to resolved community forum threads, if creating a bridge causes TrueNAS to lose external connectivity, the solution is to delete the bridge network and verify the main network interface configuration. Ensure your default gateway is correctly set and that no IP conflicts exist between the bridge and the main interface.
When setting up a bridge on TrueNAS Scale, follow the official documentation:
1. Go to Network > Interfaces and click Add.
2. Choose Bridge as the type.
3. Select the physical interfaces to include in the bridge.
4. Save and use the Test Changes mechanism before finalizing.
Occasionally, Docker may fail to start with errors about userland proxy timeouts. This typically occurs after a network configuration change or a system update.
Workaround: Check the Docker daemon logs for specific errors. Restarting the Docker service via the TrueNAS GUI or command line may resolve transient issues. If the problem persists, review your iptables rules for conflicts:
sudo iptables -t nat -L -nLook for MASQUERADE rules and ensure Docker's default rules are present.
For advanced homelab setups where you need multiple Docker bridges on different IPs or VLANs, TrueNAS community members have documented approaches using the docker network create command with specific options.
Example of creating a VLAN-specific Docker bridge:
sudo docker network create --driver=bridge \
--subnet=192.168.238.0/24 \
--ip-range=192.168.238.128/25 \
--gateway=192.168.238.1 \
--opt com.docker.network.bridge.host_binding_ipv4=10.0.7.50 \
docker_vlan7_bridgeYou can disable IP masquerading for a bridge if you plan to handle routing externally:
--opt com.docker.network.bridge.enable_ip_masquerade=falseWarning: Disabling masquerading requires you to set up custom routing and SNAT rules manually. This is only recommended for advanced users who understand network routing.
If your TrueNAS Docker containers are not working consistently or you cannot access the web interface of your applications:
1. Check container logs: Go to Apps > Installed Applications, select your app, and view the logs.
2. Verify port mappings: Ensure the host port you selected is not already in use by another service.
3. Test basic connectivity: From SSH, ping the container's IP and test external DNS resolution.
4. Restart the Docker service: In the TrueNAS GUI, go to System Settings > Services and restart the Docker service.
5. Check for IP conflicts: Ensure the container subnet does not overlap with your main network subnet.
To avoid Docker networking issues on TrueNAS Scale:
Docker networking on TrueNAS Scale can be challenging, but most issues fall into a few common categories: lost web UI access after network changes, containers without internet access, and inter-container communication failures. By understanding how TrueNAS handles Docker networks and following the troubleshooting steps in this guide, you can resolve these issues and keep your self-hosted applications running reliably.
For the latest updates and version-specific fixes, always check the TrueNAS Documentation Hub and the TrueNAS Community Forums. When in doubt, use the Test Changes feature — it can save you from losing access to your entire TrueNAS system.