Troubleshooting the "No configured local interface for altq!" Error
October 14, 2025
This error indicates that your rXg is unable to find a suitable local (LAN) network interface to apply its bandwidth management and Quality of Service (QoS) rules. Without a valid interface, the system cannot control upload/download speeds, enforce subscriber data plans, or prioritize traffic, which is a critical function for most deployments.
This article explains what ALTQ is, the common reasons this error occurs, and how to resolve it.
This article explains what ALTQ is, the common reasons this error occurs, and how to resolve it.
Understanding the Error: What is ALTQ?
At its core, ALTQ (Alternate Queueing) is the engine within your rXg that manages network traffic. It's a feature of the underlying FreeBSD Packet Filter (PF) firewall that the rXg leverages for all its traffic shaping capabilities.
Think of it as a sophisticated traffic cop for your network. Its main duties in an rXg are:
-
Bandwidth Management: Enforcing the upload and download speed limits defined in your subscriber plans.
-
Quality of Service (QoS): Prioritizing certain types of traffic (like VoIP or video conferencing) over others (like large downloads) to ensure a smooth user experience.
-
Queue Creation: Creating and managing individual traffic queues for users, plans, or VLANs to ensure fairness and prevent network congestion.
When you see the no configured local interface for altq! error, it means the rXg looked for a local, online, and configured LAN interface to act as the primary point for this traffic management, and it couldn't find one that met all the necessary criteria.
Common Causes and Solutions
The error is triggered when the rXg cannot identify any valid LAN interface for ALTQ to bind to. This usually happens in one of the following scenarios.
Cause 1: Fresh Installation or Factory Reset
A brand new or factory-reset rXg has no network configuration. The system is a blank slate and needs you to define which network port connects to your internal network (the LAN).
-
Solution: Log into the rXg and navigate to Network > Interfaces. Configure at least one interface as a LAN port by assigning it a static IP address (e.g., 192.168.1.1/24) or by adding VLANs to it.
Cause 2: All LAN Interfaces are Offline
If all your configured LAN interfaces are physically disconnected, administratively disabled, or experiencing a hardware failure, the rXg will see them as "offline" and thus unsuitable for ALTQ.
-
Solution: Ensure at least one LAN interface has a physical link (plugged-in cable) and is enabled in the Network > Interfaces section of the web UI. The interface should show an "Online" status.
WAN Cause 3: All Interfaces are Configured as WAN/Uplink
ALTQ is designed to manage traffic for local users, so it must run on a LAN interface. If every configured interface on your rXg is designated as an uplink (WAN), the system has no local port to manage.
-
Solution: Review your configuration in Network > Interfaces. Identify the interface that should be serving your local network, edit it, and remove the uplink association. Assign it a LAN IP address.
Cause 4: Specialized or Unsupported Hardware (DPUs)
Certain high-performance hardware, like NVIDIA BlueField DPUs (Data Processing Units), use interface types that are not compatible with ALTQ. These interfaces, often named tmfifo_net0 or mce0, are specifically excluded from ALTQ functionality in the rXg code.
-
Solution: If your hardware uses these interface types, you must add a standard, supported Ethernet adapter (e.g., with an igb, em, or ix driver) to your system. Configure this new interface as your LAN port for ALTQ-dependent features.
Cause 5: Cluster-Only Configuration
In a high-availability cluster, a dedicated interface is used for communication between the cluster nodes. This interconnect interface is not eligible for ALTQ traffic management. If this is the only configured interface on a cluster member, the error will occur.
-
Solution: In addition to the cluster interconnect, configure at least one other interface to serve as a LAN port for your network traffic.
Step-by-Step Resolution Guide
In most cases, the fix is to properly configure a LAN interface. Follow these steps.
-
Log into your rXg web interface.
-
Navigate to Network > Interfaces. This page lists all physical and virtual network ports on your system.
-
Identify your LAN Interface. Find the interface that is, or should be, connected to your local network. This is often igb1, em1, or a similar name.
-
Edit the Interface. Click the Edit button next to the interface.
-
Assign an IP Address. In the configuration screen, add an IPv4 address and subnet mask for your local network (e.g., 192.168.1.1/24). This tells the rXg that this is a local, configured port.
-
Save and Apply. Click Save and wait about 30 seconds for the configuration to be applied.
- Verify. Check the system's Health dashboard. The FATAL error notice related to ALTQ should disappear.
Best Practices for Prevention
To avoid this error in the future, follow these guidelines.
-
Always Configure a LAN: During any initial setup or major network change, ensure at least one interface is designated as LAN with a static IP address or VLANs.
-
Monitor Interface Status: Keep an eye on the physical link status of your interfaces. If a primary LAN port goes offline, this error could resurface.
-
Use Supported Hardware: For deployments requiring traffic shaping, use standard Ethernet interfaces that are known to be compatible with ALTQ.
-
Separate Cluster Interconnects: In cluster setups, always use a dedicated interface for cluster traffic and a separate interface for LAN traffic.
-
Keep Configuration Backups: Before making significant changes to your network configuration, always perform a backup.
Fallback Mechanism
If rXg fails to find a suitable interface, it doesn't give up immediately. It attempts a fallback process where it scans all interfaces (even unconfigured ones), filters out uplinks and unsupported types, and tries to use the most recently created interface as a last resort. If this fallback succeeds, the system will continue to function, but it will still log a FATAL health notice to alert you that the configuration is incorrect and needs to be fixed. If the fallback also fails, bandwidth management will not work at all.
Enabling and Disabling ALTQ
If your deployment does not require bandwidth management (e.g., in a high-throughput environment using 10G+ interfaces where ALTQ can be a bottleneck), you can disable it entirely.
-
Location: Configuration > Packet Options
-
Setting: "Enable ALTQ"
Disabling this setting will prevent this error from occurring, but it will also turn off all traffic shaping and QoS features system-wide.
