🚧 Work in progress: this documentation is still being written and reviewed. Check details against the source code.

Troubleshooting

When a task fails, collect these details before changing settings:

• The submitted JSON.

• The terminal action result, including its error text and completed-step count.

• The active beamline configuration.

• Relevant log messages.

A screenshot of the final GUI state may omit the backend result. Use the sections below to follow the failure from configuration through execution.

Configuration and installation

Symptom	Check	Next step
BEAMBOT_BEAMLINE_CONFIG is unset or missing	Environment in the terminal that launches the process	Export an absolute, existing YAML path before launch
Configuration reports invalid tool settings	Payload mass, center of gravity, and tool voltage for every configured tool	Correct the listed fields; the shared loader applies these checks in mock sessions too
YAML loads but poses/resources are missing	Resource values and each consumer’s path resolution	Check workspace-relative CMS paths and the configured deployment root
beambot package or action type is missing	ROS distribution and sourced install overlay	Build the workspace, source the correct overlay, inspect the package prefix
Vision/sample or pipettor action is absent	enable_vision and enable_pipettor launch values; both default to false	Enable the required feature in the intended deployment after checking its dependencies
Camera package fails during build	Imported driver, SDK, and GPU requirements	Prepare compatible camera dependencies; a launch flag does not remove build requirements
Main bringup fails importing tracing support	tracetools_launch availability	Install the required host package; tracing is imported before its condition is evaluated

Use setup and the package index to distinguish source checkout files from installed resources.

Request admission and task parsing

The orchestrator rejects new goals while busy or faulted. Read the rejection message, then check the execution state and task script before resubmitting.

For parser failures, check:

• start_gripper is present and names a tool configured in the beamline YAML.

• tasks is a non-empty list with recognized task types.

• Each MoveTo selects exactly one target mode.

• Distances are finite and positive where required.

The parser can resolve joint-pose names from the configured registry. A name left unresolved at this stage may still fail during planning.

Compare a structural error with the task JSON reference, which lists each field, its default, and the values the parser accepts.

Planning and execution

Symptom	Likely boundary to inspect
No MoveIt nodes immediately after bringup	Lazy model/stack initialization; wait for an appropriate goal before concluding startup failed
IK solver unavailable	Kinematics parameters loaded into both MoveIt and the in-process MTC nodes
Cartesian target goes to an unexpected location	Units, frame_id, IK tip frame, orientation convention, and vision offset frame
Named gripper state cannot be planned	Active SRDF, gripper group, state name, and controller mapping
Motion changes after editing a pose or scene	Plan-cache inputs and lifecycle; resolved poses affect the cache key, while live scene and model-file changes do not
Cached execution replans or repeats earlier batch motion	The log Cached replay failed (...); re-planning fresh marks fallback after a replay error other than REPLAY_TIMEOUT; inspect both attempts and replay failure handling
Preview restarts from the same pose or shows only the latest row	With batching disabled, each row starts from live CurrentState and replaces the GUI preview; see preview start states
Pause/cancel does not stop immediately	Current batch/child-action boundary and cancellation implementation
Processes or MoveIt endpoints remain after shutdown	How the launch was stopped (its own terminal or an MCP wrapper) and processes started outside MoveIt’s process group; see shutdown

For diagnosis, preserve the full planning error and active tool/model context. Change one calibration or planner setting at a time so the result identifies its effect.

Vision and tools

Check the vision inputs in order:

1. Confirm that capture produces a fresh RGB image.

2. For 3D detection, confirm that a matching organized point cloud is available. Invalid depth can prevent a 3D result even when the object is visible in 2D.

3. Confirm that TF is available for the capture’s relevant frames.

Marker dictionaries and IDs must agree with the physical markers. Marker offsets, camera mounting transforms, and tool tip offsets must agree with the actual setup. Check the transformed target against the configured tool and workspace before motion.

For ePick, distinguish observed vacuum status from automatic loss protection. The orchestrator’s vacuum monitor subscription and loss-abort checks are currently disabled. A vacuum_ok result may mean unchecked behavior in a particular path; it is not a universal seal measurement.

Changing a cup profile affects a later model launch. If the physical cup, active profile, and model disagree, resolve that configuration before interpreting approach errors.

Logs and evidence

The custom MCP get_recent_logs tool reads /tmp/beambot_launch.log, normally produced by the MCP startup wrappers. If another launch method was used, that file may be absent or stale. Inspect the terminal or the relevant ROS log directory instead.

When reporting a failure, include the exact command, source revision, logs, and action result.