ROS 2 capture service failure handling for vision systems

A failed capture should not automatically become a failed process. For a recoverable configuration or acquisition problem, the useful outcome is a completed service response explaining the failure, with the node available for another request. An unanswered call requires a different investigation: the process may have exited, the executor may be blocked, or acquisition may still be running.

This troubleshooting procedure helps you separate those cases, validate capture settings, and test recovery without confusing service availability with camera readiness.

Separate request failure from node failure

Start by recording what actually happened, rather than treating every missing image as the same fault.

A successful service discovery proves neither that the camera is ready nor that a callback can finish. Likewise, a visible node name is not a sufficient health check: graph information can briefly outlive a process, and a living process can stop servicing callbacks.

If the response completes but image delivery fails, follow returning image data from a capture service reliably. That is a different boundary from handling an unsuccessful capture request.

Check missing or invalid capture configuration first

Configuration validation is the first test because it can often be performed without changing hardware. Do not assume that an empty request means the node needs no settings. A trigger-style service may use parameters or previously loaded configuration to determine how acquisition runs.

Use the actual service and node names from your installation. The following examples assume a service named /capture and a node named /capture_node:

ros2 service list -t
ros2 service type /capture
ros2 node info /capture_node
ros2 param list /capture_node
ros2 param dump /capture_node

Then check the documented configuration requirements:

1. Confirm that a required configuration source is selected. If file and inline settings are both supported, check their documented precedence.
2. Confirm that the running process can read the selected file. A path available in a terminal may not exist inside the service's runtime environment.
3. Confirm that the configuration format matches the installed driver and acquisition library versions.
4. Check required acquisition entries, permitted parameter values, and whether configuration changes require reactivation or restart.

Do not invent parameter names or copy settings from an unrelated driver. Successful parameter assignment also does not prove that the acquisition library has parsed and accepted the settings.

For a managed lifecycle node, check its documented state requirements. For an ordinary node, do not assume lifecycle transitions are available. If initialization fails before requests can run, use camera capture pipeline startup failure diagnosis instead.

Reproduce a recoverable failure deliberately

Run the test on a stopped inspection station or isolated development setup. Choose a documented, reversible validation failure, such as an absent required capture configuration. Do not disconnect equipment during production merely to provoke an error.

Inspect the service definition before calling it. If the service type is std_srvs/srv/Trigger, these commands show its interface and issue an empty request:

ros2 interface show std_srvs/srv/Trigger
ros2 service call /capture std_srvs/srv/Trigger "{}"

That service response provides success and message fields. A recoverable failure should return success=false with an actionable explanation. This describes the desired application contract, not a guarantee about an unspecified driver.

Record four observations:

• Did the client receive a response?
• Did the response identify failure accurately?
• Did the process remain running and responsive?
• After correcting configuration, could another request succeed?

Service visibility alone does not establish the last two points. Inspect process health, then make a controlled follow-up request. Keep the test sequential so overlapping requests cannot obscure the result.

If the node exits, inspect the exception boundary

When the process disappears, look for the earliest relevant error, not just the final shutdown message. A parser error, acquisition exception, explicit termination, and native process fault require different fixes.

Compare logs immediately before the request with logs immediately after it. Record whether request validation started, whether acquisition began, and whether the response path was reached. Check the process exit status through the launch mechanism or supervisor.

In a composed deployment, determine whether the component stopped or the entire container exited. An uncaught failure can affect other components sharing the process; the deployment boundary matters when assessing recovery.

For maintained drivers, obtain supported releases and recovery guidance from the manufacturer or its authorized distributors. Do not assume an issue reported for another release describes your installation.

If you maintain the service implementation, handle expected validation and acquisition errors at the request boundary. Do not treat memory corruption, an invalid internal state, or a failed safety-related dependency as ordinary request failures merely to keep the process alive.

If the node stays alive, check blocking and executor behavior

A living process with an unanswered request is not necessarily experiencing an exception. Start with the callback timeline:

1. Log entry into the service callback.
2. Log completion of configuration validation.
3. Log entry and return around acquisition.
4. Log the response status immediately before returning.

If acquisition never returns, inspect the acquisition library's documented timeout and recovery mechanisms. If the callback is waiting for another callback, inspect executor and callback-group arrangements.

A synchronous wait inside a callback can prevent the callback needed to satisfy that wait from running. A multithreaded executor alone does not resolve every arrangement; callback groups and shared locks still constrain execution.

If the response path completes but the client remains waiting, inspect the client future, executor progress, and middleware logs. Avoid assigning a transport cause until the server timeline supports it.

For failures that also occur outside the service wrapper, continue with intermittent camera acquisition failure troubleshooting. This separates request-handling defects from acquisition failures that the wrapper merely exposes.

Bound the client wait without assuming cancellation

Give the application a finite response deadline, even when the server is expected to report every recoverable error. A process crash or blocked operation can still prevent a response.

Use measured end-to-end behavior to establish the deadline. Include validation, acquisition, processing, response delivery, and scheduling margin:

For an illustrative station, suppose the budgets are 40 ms, 600 ms, and 160 ms, with a 200 ms margin:

Client deadline = 40 + 600 + 160 + 200 = 1000 ms

These are example application budgets, not camera specifications or universal recommendations. Measure representative operating conditions before selecting production values. Use a monotonic clock for elapsed-time decisions.

A client timeout does not prove that the server stopped acquiring. It also does not establish that a retry is safe. Do not immediately submit another request if the first operation may still be active.

The distinction between request submission and actual exposure is covered in trigger call versus exposure time. For matching delayed outputs to work items, use asynchronous result and frame matching.

Define the response and recovery contract

For a service you maintain, make unsuccessful outcomes explicit. Validate required settings before beginning acquisition, then translate expected failures into the documented response format.

A useful failure message identifies the stage and correction: configuration was absent, configuration could not be parsed, or acquisition failed and requires a documented recovery step. Keep detailed diagnostics in logs without exposing credentials or sensitive configuration.

Before accepting another request, release resources and restore a known acquisition state. If that cannot be done, mark capture unavailable and follow the documented recovery procedure rather than accepting work that cannot complete.

Use this acceptance matrix to verify the implementation:

As an example acceptance run, alternate 10 invalid requests with 10 corrected requests. Expect 20 completed responses and successful recovery after every corrected configuration. This is a regression test, not proof that every fault is recoverable.

Check compatibility before changing hardware

Replacing a camera does not repair an exception boundary or executor deadlock. First establish whether acquisition succeeds through the supported acquisition interface outside your service wrapper.

When selecting area scan cameras, use the camera finder to narrow the interface and imaging requirements. Then verify driver support for your operating system, architecture, ROS distribution, and required capture features separately.

The LS-CMR-0053 is a GigE area scan camera. Its interface does not establish compatibility with a particular ROS package.

The LS-CMR-0166 is a USB3 area scan camera. Confirm the complete software acquisition path before selecting it for a ROS deployment.

For vision controllers, check supported software, camera interfaces, executor workload, and recovery supervision. Hardware availability and software compatibility are separate acceptance questions; neither a camera interface nor a controller category promises a ready-made ROS integration.

Finish with a repeatable recovery checklist

Before returning the station to service, confirm:

• Required capture settings are validated before acquisition starts.
• Recoverable failures produce completed, meaningful responses.
• The node remains responsive after those failures.
• Correcting settings permits a successful follow-up capture.
• Client deadlines are finite and do not trigger uncontrolled retries.
• Late images cannot be mistaken for a later work item.
• Unrecoverable faults produce a defined unavailable state or supervised restart.
• The same tests run after driver, library, or configuration changes.

The usual answer—keep the node alive—is wrong when its acquisition state cannot be trusted. Availability means being able to accept and complete valid work, not merely retaining a process identifier.

For hardware selection, start with the camera configuration step. For a compatibility review, send the service type, software versions, effective settings, and failure timeline through technical support.