GigE incomplete frames from a driver and NIC MTU mismatch

A camera that streams perfectly in the viewer but drops every frame the moment your application starts is not a broken camera. It is a packet-size disagreement. Your driver asks the camera for 9,000-byte packets, while the host network card or a switch in the path still runs at MTU 1500 and silently discards every oversized packet, so the driver logs INCOMPLETE 100%. Stop the driver and even the viewer can go black, because the camera keeps the bad settings.

This guide is for engineers running GigE area scan cameras on Linux hosts, usually through a PoE switch. You will confirm the mismatch with two checks, choose between the two fixes using bandwidth arithmetic, and recover a camera left refusing streams.

What a 100% incomplete rate means on the wire

GigE Vision carries each frame as a burst of fixed-size network packets. The receiving driver reassembles them, and if even one packet is missing it marks the whole frame incomplete rather than handing you a torn image. That is the mechanism doing the reporting, not a fault in your grab loop.

A network card cannot deliver a 9,000-byte packet through an interface with MTU 1500, so the frame never reaches your application, and nothing on the receiving side logs an error. The pattern tells you which failure you have. Losses from a marginal cable or a congested link arrive in bursts and percentages; a uniform 100% rate at a fixed configuration is arithmetic, not physics — some hop is discarding a packet size it was never set up to carry.

In your own code, discard incomplete frames and grab a fresh one instead of publishing them; the incomplete-frame discard and requeue pattern shows the handling.

Why the viewer streams while your driver drops everything

One camera, two clients, two different requests. The viewer negotiates a packet size that fits the network it finds, 1500 or less on a default install. Your driver's configuration pins the size explicitly:

gev_scps_packet_size: 9000

The camera now emits IP packets of 9,000 bytes. Every interface and every switch port in the path must carry them; the moment one hop still runs at 1500, packets vanish and every frame fails the completeness check. The camera, cable and switch are all doing exactly what they were told.

Negotiation is also capped by what the driver reports about the interface, which is how the two clients end up disagreeing; the packet size exceeds MTU cap and the packet-size setup order before acquisition both cover that side.

The bench behind this symptom is ordinary hardware:

Find the mismatch with two checks

1. Read the driver configuration. Find the packet-size setting in your launch file or YAML. A value of 9000 next to a viewer that streams is the signature of this failure.
2. Read the host MTU. Run ip a and look at the interface on the camera's subnet; mtu 1500 beside a 9,000-byte request confirms it.

Then walk every hop between camera and host. A direct NIC-to-camera link has two ends; a switched link has the camera port, both switch ports and the switch's frame-size setting. Any single hop at 1500 reintroduces the drop.

Prove the path end to end with one oversized ping: ping -M do -s 8972 <camera IP>. The 8,972-byte payload plus 20 bytes of IP header and 8 bytes of ICMP header make exactly a 9,000-byte packet, and the do flag forbids fragmentation, so a pass means every hop carries jumbo frames. If your driver or viewer offers a GigE Vision test-packet check, run that too; the test packet not received fix covers its failure modes.

Fix 1: turn on jumbo frames end to end

Raise the MTU everywhere the stream touches, then restart acquisition.

1. Set the host interface: sudo ip link set dev <interface> mtu 9000.
2. Make it survive reboots by writing the MTU into the interface's connection profile (netplan or NetworkManager on most installs), not just into the runtime command.
3. Enable jumbo frames on the switch ports the camera and host use. Do not stop at 9,000: the on-wire Ethernet frame is 9,000 + 14 + 4 = 9,018 bytes, 9,022 with a VLAN tag. A jumbo setting of 9,216 covers it; a switch capped at exactly 9,000 drops every packet anyway.
4. Re-run the 8,972-byte ping until it passes through every hop.
5. Restart the driver and watch the log: incomplete should hold at 0% at full frame rate.

MTU is a frame-size setting and does not touch PoE power delivery, so a camera powered from the switch keeps its negotiated power class through the change.

Fix 2: keep the packet size at 1500

If the switch is off limits — shared plant infrastructure, an IT-owned device — stop asking for jumbo packets instead. Set the packet size to 1500 in the driver configuration, or delete the override so the driver negotiates a size the link already carries, and leave every MTU alone.

gev_scps_packet_size: 1500

This works whenever the stream's bandwidth fits a gigabit link, and it needs nobody's permission. A 2 MP stream at 40 fps needs about 83 MB/s, which fits comfortably; the arithmetic for your own camera is the next section.

Does your stream need 9,000-byte packets?

Jumbo frames do not add bandwidth. They cut the packet count, and with it interrupt and CPU load, while the byte rate stays identical. Whether you need them is one calculation:

Worked example: a 1920 × 1080 mono camera in 8-bit Bayer (BayerRG8) at 40 fps.

• 1920 × 1080 = 2,073,600 bytes per frame
• 2,073,600 × 40 = 82,944,000 bytes per second, about 82.9 MB/s or 664 Mbit/s
• A gigabit link moves 1,000 Mbit/s raw, roughly 118 MB/s of payload once GigE Vision, IP and UDP overheads are paid; budget about 110 MB/s to keep margin

82.9 MB/s fits with room to spare, so packet size 1500 is fine and jumbo is optional. What jumbo buys instead is packet rate. Assume each packet carries about 50 bytes less image data than its nominal size, once GVSP, UDP and IP headers are paid: a 1500-byte packet moves roughly 1,450 bytes, so one frame takes 2,073,600 / 1,450 ≈ 1,430 packets, about 57,000 packets per second at 40 fps. At packet size 9000 it is 2,073,600 / 8,950 ≈ 230 packets, about 9,300 per second. Same bytes, roughly one sixth of the packet rate — gentler on the host, no faster on the wire.

The opposite case decides for you. A 12 MP mono stream, 4,000 × 3,000 at 30 fps, moves 12,000,000 × 30 = 360 MB/s, about 2.88 Gbit/s — three times a gigabit. No packet size fixes that. Cut bytes first (ROI, binning, a lower frame rate), then move the link: 2.5G interfaces carry roughly 290 MB/s of payload and 10G roughly ten times a gigabit. The 5GBASE-T interface guide covers cable and distance limits on faster links.

Host NICs that carry GigE Vision streams:

All 3 share: Humidity 10% RH to 95% RH (no condensation). Values as printed in each product's data sheet; open a part for its drawing and full specifications.

The MV-GE4004 is a quad-port 2.5G Ethernet adaptor. Streams in the roughly 110-280 MB/s band belong on hardware like that, not on gigabit; the GigE frame grabbers category holds the rest, including multi-port cards that isolate cameras from one another.

When the link stays black after a bad session

A driver run with bad settings can outlast the process. The camera holds its configured packet size and throughput limit in volatile memory, so afterwards even the viewer — negotiating politely against a camera that insists on 9,000-byte packets — shows black.

Recover in this order.

1. Reset the camera from the viewer's reset control, which restores factory defaults including network settings, or power-cycle it.
2. If the camera no longer answers on the network at all, use the viewer's network configuration tool to put its IP back on your subnet, then reset.
3. Only then change MTU or packet size. Fixing settings before resetting just re-arms the failure at the next start.

The throughput limit deserves the same discipline. A configuration that sets device_link_throughput_limit: 380000000 asks the camera to emit 380 MB/s, more than three times what a gigabit link carries (~118 MB/s of payload). Keep the limit at or below what the link actually delivers, or leave it at its default and let the camera pace itself. And if your configuration loads a stored user set, check the set was saved with sane network values; a bad value re-loads at every start.

The camera rediscovery after a resource error guide walks the recovery path in detail.

If it is not MTU: other causes in order of probability

Once packet size matches every MTU in the path, work down this list.

1. Link speed below gigabit. A port that negotiated 100 Mbit/s fails loudly at configuration time with a packet-size error rather than silently; the packet-size error on a sub-gigabit link covers that case. Check with ethtool <interface> | grep -i speed.
2. Cable and connectors. A damaged or over-length patch cable loses packets in bursts, so the incomplete rate runs high but not at a clean 100%. Swap in a known-good GigE cable with locking connectors and take the variable off the bench.
3. NIC buffer drops under load. Several cameras into one card can overflow receive buffers even when each link is healthy. Start with the NIC tuning order for missing packets, then the host bandwidth budget for two cameras on one NIC; the heavy multi-camera bad-frames checklist covers the general case.
4. PoE budget and port stability. A switch that cannot supply the camera's power class resets it mid-stream, which shows up as incomplete bursts plus discovery dropouts; the PoE stream-drop and recovery guide covers the watchdog timeouts.

Keep it fixed

• Persist the MTU in the connection profile so a reboot or link flap cannot quietly return it to 1500.
• Keep packet size and required MTU together in the configuration, with the reason in a comment: # 9000-byte packets need MTU 9000 on host and 9216 on switch ports.
• Never set device_link_throughput_limit above what the link delivers; on gigabit that means about 110 MB/s or less.
• After any switch firmware update or port change, re-run the 8,972-byte ping before starting acquisition.
• Prove the camera in the viewer at default settings before starting the driver; if the viewer cannot stream, the driver will not either.

More fixes in this family sit on the systems topic page.

The decision

• Driver asks for 9,000-byte packets, host or switch runs MTU 1500, viewer streams at defaults: that is this failure. Raise MTU to 9000 on the host and 9216 on every switch port, or pin the packet size to 1500.
• Stream needs up to about 110 MB/s: stay on gigabit at packet size 1500.
• Stream needs roughly 110-280 MB/s: jumbo frames plus a 2.5G NIC.
• Beyond that: ROI, binning or a lower frame rate first, then a 5G or 10G link — bigger packets never add bandwidth.
• Viewer black after a driver run: reset or power-cycle the camera, fix the MTU, then restart the driver.

If you are speccing the hardware side, the camera finder filters GigE models by resolution and interface, the build-a-system configurator assembles camera, NIC and cables as one checked list, and the contact page is the way to a second opinion on a stubborn link.