Errors and Troubleshooting

MetriCal logs various error codes during operation or upon exiting. The documentation here catalogs these errors, along with descriptions (🔍) and troubleshooting (🔧) steps. While there are a large number of errors that can occur for various reasons, we do our best to keep this aligned with the current collection of error codes and causes that we find in our products.

If we've missed something here, or if you need additional clarification, please contact us at support@tangramvision.com.

Error Codes in Logs

During operation, error codes may be printed to the log (stderr) as informational warnings or as errors that caused MetriCal to fail and exit. These are usually coded as cal-calibrate-001 or license-002 or something similar. In addition to these codes, there are usually anchors or sections in the docs that relate to each individual code.

MetriCal Exit Codes

When exiting, MetriCal will print the exit code and return it from the process. The table below lists the exit codes and a description of what each code means.

Exit Code	Error Type	Notes
0	Success, No Errors	Good Job!
1	IO	Filesystem and Input/Output related errors
2	Cli	Command Line Interface related errors
3	ShapeMode	Shape related errors
4	InitMode	Init related errors
5	Pretty Print	Historical exit code, unused
6	MetriCalLicense	License related errors
7	Display mode	Historical exit code, unused
8	CalibrateMode	Calibrate related errors
9	Completion mode	Historical exit code, unused
10	Rendering	Rendering related errors
11	Consolidate object space	Historical exit code, unused
12	Diagnostic	An error-level diagnostic was thrown
13	Format	Errors whose source can be traced back to some issue based on trying to read or write the expected file format
14	Manifest	Errors related to processing MetriCal Manifest files
15	PlexMode	Plex related errors
16	SpecMode	Spec related errors
255	Other	Other unspecified errors (u8::MAX = 255)

Error Sub-Codes

Many codes have sub-codes that describe the specific error that occurred. Find a list of relevant sub-codes below.

Code 1: IO Errors

Filesystem Error (cal-io-001)

🔍 Error when performing an operation on a file on the filesystem.

🔧 Check that the file exists, you have the necessary permissions to read/write it, and that the file path is correct. Verify that there's sufficient disk space if writing files. Also ensure the file isn't locked by another process.

Memory Map Failure (cal-io-002)

🔍 Failed to memory map the provided file.

🔧 This error occurs when the system cannot create a memory-mapped view of the file. Check that:

• The file exists and is accessible
• You have sufficient memory available
• The file isn't corrupted or locked by another process
• Your system supports memory mapping for files of this size

Cached Detections for Wrong Plex (cal-io-003)

🔍 The cached detections read in for this dataset did not match the component UUIDs in this plex.

🔧 The cached detection data was generated for a different plex configuration. Clear your cache and regenerate the detections, or ensure you're using the correct plex file that matches the cached detections.

Code 2: CLI Errors

Missing Component (cal-cli-001)

🔍 There is no component with the specified UUID or name in the provided plex.

🔧 Using the init command to create a plex ensures that all components are properly named and assigned a UUID according to the dataset being processed.

Duplicate Component Specification (cal-cli-002)

🔍 The same component has been specified more than once.

🔧 Comparing a component to itself just gives identity. This is good news: The rules of the universe are still intact.

Ambiguous Topic Mapping (cal-cli-003)

🔍 There are ambiguous topic-to-component mappings.

🔧 If you're using a glob matching pattern (i.e. -m *image*:___), make sure that there aren't glob patterns between assignments that could be interpreted as a duplicate.

Invalid Key-Value Pair (cal-cli-004)

🔍 Invalid key:value pair provided as an argument. No ':' found in the argument.

🔧 Format this argument as key:value.

Invalid Model (cal-cli-005)

🔍 The provided model is not recognized by MetriCal.

🔧 There are different models depending on the component type. Check the documentation for valid model names for your component type.

Component Model Already Assigned (cal-cli-006)

🔍 Cannot assign component name to topic; a component already exists in the plex with this name.

🔧 Choose a different component name or check if the component is already properly configured in your plex.

Output Would Be Overwritten (cal-cli-007)

🔍 Previous file already exists at the specified path.

🔧 Deleting the file at the path above can remove this error; however, this may result in data loss. If this file is a plex or object space, this can cause some associations to become lost, like component relations in cached detections.

Reference the --overwrite-strategy and --uuid-strategy arguments for more details on how to handle this behavior.

No Plex in MCAP (cal-cli-008)

🔍 The MCAP at the specified path did not contain a plex.

🔧 Make sure that the provided MCAP file is a results MCAP from MetriCal.

No Object Space in MCAP (cal-cli-009)

🔍 The MCAP at the specified path did not contain an object-space.

🔧 Make sure that the provided MCAP file is a results MCAP from MetriCal.

Missing Camera Motion Threshold (cal-cli-010)

🔍 The provided plex contains camera components, but no camera motion filter was specified.

🔧 Specify a camera motion filter using the --camera-motion-threshold argument.

Missing Lidar Motion Threshold (cal-cli-011)

🔍 The provided plex contains lidar components, but no lidar motion filter was specified.

🔧 Specify a lidar motion filter using the --lidar-motion-threshold argument.

Variable Needs Substitution (cal-cli-012)

🔍 Variable needs substitution but is missing.

🔧 The variable is referenced but not defined. Define it in the manifest or pass it via command line.

Invalid Output Reference (cal-cli-013)

🔍 Invalid output reference that cannot be parsed.

🔧 Output references must be a file path or a blank string (""), which indicates the default filepath for that output in your workspace. Outputs as variable values are not permitted. Check your manifest for typos.

Invalid Input Reference (cal-cli-014)

🔍 An input reference could not be parsed.

🔧 Input references must be a file path, a variable template (e.g. {{variables.name}}), or a stage output reference (e.g. {{stage.field}}). Check your manifest for typos; the error suggests a corrected spelling when a close match exists.

Display Requires Data Or Plex (cal-cli-015)

🔍 display was invoked with neither a dataset nor a plex/results file.

🔧 Pass --data <path> to render a dataset, --plex <path> to render plex structure (frustums, ray maps, optimized poses), or both to render the dataset with the plex applied.

Code 3: Shape Errors

No Valid Tabular Components (cal-shape-001)

🔍 None of the components passed to the Shape::tabular command exist, so there was nothing to do.

🔧 Verify that the component names or UUIDs you specified exist in your plex. Check for typos in component names and ensure that the components are in your plex configuration.

Component Cannot Make LUT (cal-shape-002)

🔍 The specified component is not a camera, so MetriCal can't produce LUTs.

🔧 Look-up tables (LUTs) can only be generated for camera components. Ensure that you're specifying a camera component for LUT generation. Check your plex to verify the component types.

Bad Stereo Configuration (cal-shape-003)

🔍 The two cameras can't be a stereo pair, since there is no spatial constraint between them in the provided plex.

🔧 You can reference a component either by its name or UUID. Ensure that there is a valid spatial relationship (transformation) defined between the two camera components in your plex for stereo pair configuration.

Missing Root Component (cal-shape-004)

🔍 The root component does not exist.

🔧 You may specify the root component by either its name or UUID. Verify that the component exists in your plex and that the name or UUID is spelled correctly.

URDF Write Failure (cal-shape-005)

🔍 The URDF could not be converted to a String.

Builder Error (cal-shape-006)

🔍 Failed to construct a plex from this URDF.

🔧 This error occurs during plex construction from URDF data. Verify that your URDF file is properly formatted, contains valid robot description data, and that all referenced components and links are correctly defined. Check for missing joints, invalid transformations, or malformed XML structure.

Code 4: Init Errors

Could Not Create Camera (cal-init-001)

🔍 Could not create a camera from the provided data for the specified component.

🔧 Verify that the data for this component contains valid image observations.

Could Not Create Lidar (cal-init-002)

🔍 Could not create a lidar from the provided data for the specified component.

🔧 Ensure that the data for this component contains valid lidar observations.

Could Not Create IMU (cal-init-003)

🔍 Could not create an IMU from the provided data for the specified component.

🔧 Check that the data for this component contains valid IMU observations.

Impossible Image Resolution (cal-init-004)

🔍 Last read image for topic has a width or height of 0 px.

🔧 Check your image data to ensure that images have valid, non-zero dimensions. This may indicate corrupted image data or an issue with the image encoding.

Image Resolution Inconsistent (cal-init-005)

🔍 Last read image for topic has a resolution inconsistent with previous images.

🔧 Ensure that all images in a topic have the same resolution. MetriCal requires consistent image dimensions throughout the stream for proper camera calibration.

No Topics Found (cal-init-006)

🔍 None of the requested topics were found or readable in this dataset.

🔧 Check that the topics you specified exist in your dataset and are in a format that MetriCal can read.

No Data to Init (cal-init-007)

🔍 MetriCal was not able to create a Plex from the init data.

🔧 This error could be for a few reasons:

• None of the topics requested exist in the dataset provided.
• The dataset provided is empty.
• The requested topics in the dataset provided are not in a format that MetriCal can read.

If any of these apply, please check the dataset and try again.

Could Not Create Radar (cal-init-008)

🔍 Could not create a radar from the provided data for the specified component.

🔧 Verify that the data for this component contains valid radar observations.

Could Not Create Local Navigation System (cal-init-009)

🔍 Could not create a local navigation system from the provided data for the specified component.

🔧 Ensure that the data for this component contains valid local navigation system observations.

Could Not Create Transform Tree (cal-init-010)

🔍 Could not create a transform tree from the provided data for the specified component.

🔧 Check that the data for this component contains valid transform tree observations.

Code 6: License Errors

Response Verification Failed (license-001)

🔍 Verifying the license via API failed.

🔧 Ensure no network proxy is modifying HTTP content or headers. This can happen if the response's signature could not be verified, the response could not be properly decoded, or the response did not contain a necessary field. Contact support@tangramvision.com if the issue persists.

No Credit (license-002)

🔍 The software was unable to get any credits from the licensing server.

🔧 Check your connection, and log into the Hub to see if your credit balance is positive. If you believe this is in error, contact support@tangramvision.com for more assistance.

Cached License Key Mismatch (license-011)

🔍 The provided license key does not match the key in the license-cache file.

🔧 If you maintain different license-cache files (e.g. for different users), ensure you're using the license-cache file that matches the provided license key. Otherwise, delete your license-cache file and try again.

License Key Not Found (license-015)

🔍 No license key was found from any source.

🔧 Provide a license key via CLI argument, environment variable, or config file.

MetriCal checks for a license key from one of three source, in order:

1. The provided key from the --license argument
2. The TANGRAM_VISION_LICENSE environment variable
3. The configuration file located at XDG_CONFIG_HOME/tangram-vision/config.toml. This usually expands out to be something like ~/.config/tangram-vision/config.toml.

See our licensing configuration page for more information on how to correctly set these.

License API Error (license-018)

🔍 An error occurred while querying the Hub API for license information.

🔧 Please review the included error message for more information. This could be due to network connectivity issues, API service unavailability, or authentication problems.

Cached License Product Mismatch (license-020)

🔍 The cached license file is for a different product.

🔧 The offline license cache on this machine was issued for a different product. Refresh your license with network access, or provide a license key that matches this product.

Enterprise License Not Found (license-021)

🔍 The provided license is not an enterprise license, but an enterprise license is required to use this software.

🔧 Check that you have not accidentally set more than one license source with an incorrect key. Common license sources are the --license command argument, the TANGRAM_VISION_LICENSE environment variable, and the configuration file. If you are currently using credits and are interested in upgrading to an enterprise plan, contact support@tangramvision.com.

No Valid License Sources (license-022)

🔍 License keys were provided to the program, but no valid license sources were found.

🔧 This can arise from missing network connectivity, proxy settings, a lapsed payment, a key revoked by a group admin, an expired offline license cache (enterprise-only), or a typo or invalid key for this product. Check that your network is connected and that your license key has been entered following the documentation. For additional context, re-run the command with the network enabled and with debug verbosity (add the -v flag), and contact support@tangramvision.com if you need further assistance.

Code 8: Calibrate Errors

No Features Detected (cal-calibrate-001)

🔍 No features were detected from any specified object space, or the feature count per observation was too low for use.

🔧 This indicates an issue in your object space. There are a number of things that could have happened. Here are just a few suggestions:

• Verify the measurements of your fiducials. These should be in meters.
• Verify the dictionary used for your boards, if applicable. For example, a 4x4 dictionary has targets made up of 4x4 squares in the inner pattern of the fiducial.
• If this is a Markerboard, make sure that you have checked that your initial_corner is set to the correct variant ('Marker' or 'Square').
• Make sure you can see as much of the board as possible when collecting your data. Tangram filters detections that are all collinear, or detections which have fewer than 8 identified points in the image.
• Try adjusting your Camera or LiDAR filter settings to ensure that all detections are not filtered out.
• Running with cached detections? Your object space may have changed since the cached detections were generated. Try clearing your cache and re-running.

Detector Error (cal-calibrate-002)

🔍 There was an error when working with the detector.

🔧 Check your detector configuration and ensure that your input data is compatible with the selected detector.

Calibration Failed to Complete (cal-calibrate-003)

🔍 Failed to run calibration to completion.

🔧 Review your calibration parameters and input data. This error typically indicates issues with the least squares solver during optimization.

Calibration Solution Interpretation Failed (cal-calibrate-004)

🔍 Failed to interpret the calibration solution.

🔧 The calibration completed but the results could not be properly interpreted. Check your calibration configuration and data quality.

No Compatible Component Type (cal-calibrate-005)

🔍 There is no compatible component type to register against, so the calibration can't proceed.

🔧 Different component types rely on different modalities to support their calibration:

• Cameras: no dependency
• Lidar: requires another lidar or a camera
• IMU: requires a camera
• Local Navigation System (LNS): requires a camera

If processing any of these modalities, make sure these conditions are met before proceeding. Alternatively, remove this component from the calibration process.

Compatible Component Has No Detections (cal-calibrate-006)

🔍 This data had a compatible component type to register against, but that component type had no detections.

🔧 Different component types rely on different modalities to support their calibration:

• Cameras: no dependency
• Lidar: requires another lidar or a camera
• IMU: requires a camera
• Local Navigation System (LNS): requires a camera

One or more components could be paired with a compatible component type, but that other component type didn't have any usable detections! Gather more detections to calibrate this component.

Compatible Component Detections Filtered (cal-calibrate-007)

🔍 This data had a compatible component type to register against, but all observations from that component type were filtered out from motion.

🔧 Different component types rely on different modalities to support their calibration:

• Cameras: no dependency
• Lidar: requires another lidar or a camera
• IMU: requires a camera
• Local Navigation System (LNS): requires a camera

One or more components could be paired with a compatible component type, but that other component type had all of its detections filtered out by the motion filter! We recommend taking another dataset, this time with pauses during motion. That, or raise the motion filter threshold.

Camera Pose Estimate Failed (cal-calibrate-008)

🔍 The initial camera pose optimization failed to converge.

🔧 According to the optimization, there were camera detections for which a sane camera pose could not be derived. This may indicate an error in image readout, or an egregiously poor intrinsics initialization by MetriCal. Try two things:

• Increase this camera's focal length in the init plex. This might just do the trick.
• Review this camera's data for anything unusual. Any corrupt images or bad detections could be causing this issue.

License Server Contact Failed (cal-calibrate-009)

🔍 MetriCal was unable to report a successful calibration to the licensing server.

🔧 Because your license tier has metered calibrations, MetriCal needs to contact the license server to register each successful calibration. Even though your calibration succeeded, we were unable to reach the license server at this time and therefore cannot output calibration results.

No Camera Poses Derived (cal-calibrate-010)

🔍 No valid camera poses could be derived for a camera during initialization.

🔧 Camera initialization failed to produce any valid poses for this camera. This usually means the camera's intrinsics initialization is too far off, or the detections are too noisy or too few to solve. Try:

• Providing a closer focal length estimate in the init plex.
• Checking this camera's images for poor quality, motion blur, or very few fiducial detections.
• Ensuring the object space definition matches the physical target.

Duplicate IMU Samples Detected (cal-calibrate-012)

🔍 Duplicate IMU samples were detected for the same UUID at the exact same timestamp.

🔧 Duplicate IMU samples were detected at the same timestamp for the same component (IMU) UUID. This means that two (distinct) IMU samples were written into the data at the exact same time from the same IMU. Often, this indicates an issue in double-recording the data, or some other timestamp issue in how the data was generated.

As a first measure, check your recorded data and try to evaluate how this occurred.

You may also find it helpful to run metrical-display over your data to visually inspect the data in the provided IMU plots. Make sure that the AggregationPolicy in your visualization of each specific-force or gyro stream is set to Off, or you may not be able to see duplicate IMU samples.

This is a fatal error that MetriCal cannot work around, and will not be able to calibrate. If you would like to proceed with the rest of the calibration, remove the offending component from your Plex and rerun the calibration.

Duplicate Tag IDs Detected (cal-calibrate-013)

🔍 Duplicate fiducial tag IDs were detected at distinct locations in the same image.

🔧 Each tag ID must appear at most once in any single image. Duplicate detections make it impossible to determine which physical tag corresponds to which detection, so the calibration cannot proceed. Common causes:

• Two boards in the scene have overlapping tag ID ranges; assign non-overlapping marker_id_offset values in your object space configuration.
• The same board is visible twice (e.g. reflected in a mirror or glass surface).
• A manufacturing defect produced two tags with identical encoding.

Insufficient IMU Motion Excitation (cal-calibrate-014)

🔍 An IMU has insufficient motion excitation for calibration.

🔧 Poor motion excitation cannot be compensated for mathematically. If the data does not exercise all rotational and translational axes, the IMU calibration will fail and degrade results for every other sensor in the system. To proceed without this IMU, remove it from your Plex by running metrical plex filter -i <input_plex> -o <output_plex> --restriction exclude <imu_name_or_uuid>, then rerun calibration with the filtered plex. Alternatively, re-collect data with more varied motion across all rotational and translational axes.

Code 10: Rendering Errors

Missing Recording Stream (cal-rendering-001)

🔍 No global Rerun connection found.

🔧 Ensure that a global Rerun connection is established. The rendering system requires an active Rerun connection to visualize data.

Observation Incompatible (cal-rendering-002)

🔍 The observation wasn't compatible with the render function called.

🔧 Check that you're using the correct rendering function for your observation type. Each render function is designed for specific observation types - make sure the observation matches the intended type for the function you're calling.

Empty Object Space (cal-rendering-003)

🔍 This object space is empty of renderable objects.

🔧 Ensure that your object space contains valid renderable objects before attempting to render it. Check that the object space has been properly populated with geometric or visual elements.

Missing Component (cal-rendering-004)

🔍 There is no component with the specified name in the plex.

🔧 Verify that the component name exists in your plex configuration. Check for typos in the component name and ensure that the component has been properly defined and initialized in the plex.

Recording Stream Error (cal-rendering-005)

🔍 A Rerun recording stream error occurred.

🔧 This is an error from the underlying Rerun library. Check the Rerun connection status, ensure the Rerun viewer is running if needed, and verify that the recording stream configuration is correct.

Image Conversion Error (cal-rendering-006)

🔍 An image conversion error occurred.

🔧 This error occurs when converting image data for rendering. Check that your image data is in a supported format, has valid dimensions, and that the pixel data is not corrupted. Ensure the image encoding matches what's expected.

Empty Observation (cal-rendering-007)

🔍 Cannot render an empty observation.

🔧 The observation contains no data to render. Ensure that your observation has valid data before attempting to render it. Check that data collection was successful and that the observation is properly populated.

Code 12: Diagnostic Errors

🔍 Error-level data diagnostic detected; calibration failed.

🔧 Since an Error-level data diagnostic was thrown, MetriCal will not output a calibration results file by default. If your license plan includes a limited number of calibrations, runs that do not produce a calibration results file will not count toward that limit.

This safeguard can be overridden by passing the --override-diagnostics flag to the calibrate command. This will allow you to get a calibration if you feel your data has been wrongly diagnosed as insufficient. However, this will count toward your calibration limit.

Code 13: Format Errors

JSON Deserialization Error (cal-format-001)

🔍 Failed to deserialize data from source JSON.

🔧 Check that your JSON file is properly formatted and contains valid syntax. Look for missing commas, brackets, or quotes. The error message will indicate the specific line and column where the parsing failed.

TOML Deserialization Error (cal-format-002)

🔍 Failed to deserialize data from source TOML.

🔧 Check that your TOML file is properly formatted and follows TOML syntax rules. Verify that keys are properly quoted, values have the correct types, and tables are properly structured.

JSON Serialization Error (cal-format-003)

🔍 Failed to serialize data to JSON format.

🔧 This usually indicates an internal issue with data structures that cannot be represented in JSON. Contact support@tangramvision.com.

MCAP File Error (cal-format-004)

🔍 Failed to read something from an MCAP file.

🔧 Ensure that the MCAP file is not corrupted and is a valid MCAP format. Check that you have read permissions for the file and that it was created with a compatible version of the MCAP library.

URDF File Error (cal-format-005)

🔍 Failed to read from a URDF file.

🔧 Verify that your URDF file is valid XML and follows the URDF specification. Check for proper tag closure, valid attribute values, and ensure that all referenced files (meshes, textures) exist and are accessible.

MessagePack Serialization Error (cal-format-006)

🔍 Failed to write/serialize a struct to MessagePack format.

🔧 This indicates an issue with serializing data to the MessagePack binary format. Check that all data types in your structure are supported by MessagePack and that there are no circular references in your data.

MessagePack Deserialization Error (cal-format-007)

🔍 Failed to read/deserialize a struct from MessagePack format.

🔧 This indicates an issue with deserializing data from the MessagePack binary format. Contact support@tangramvision.com.

Code 14: Manifest Errors

Missing Required Variables (cal-manifest-001)

🔍 Missing/misconfigured variables needed for manifest execution.

🔧 Configure the missing and misconfigured variables using --set VARIABLE=<value>. Check that all referenced variables are properly defined and that their values are valid for your manifest configuration.

Manifest Structure Cycle (cal-manifest-002)

🔍 Circular dependency detected in manifest structure.

🔧 The manifest has a circular dependency that prevents proper execution order. Remove dependencies that create cycles in your manifest. Check the dependency chain and ensure that stages don't reference each other in a loop.

Invalid Stage Reference (cal-manifest-003)

🔍 Invalid stage reference in the manifest.

🔧 Ensure that all stage references point to valid, existing stages in your manifest. The error names the field and stage that contain the bad reference, and suggests a similarly-named stage when one exists. Check for typos in stage names and verify that referenced stages are properly defined.

Forward Stage Reference (cal-manifest-004)

🔍 Forward stage reference: a stage cannot reference another stage that comes later in execution order.

🔧 Stages execute in the order they appear in the manifest. Move the referenced stage before the current stage, or reference an earlier stage instead. The execution order must follow a linear progression.

Stage Named Reserved Word (cal-manifest-005)

🔍 Stage name is reserved and cannot be used.

🔧 The specified stage name is reserved for manifest parsing. Please rename this stage to something else. Reserved words are used internally by the manifest system and cannot be used as stage names.

Template Parse Failure (cal-manifest-006)

🔍 A template expression in a reference string could not be parsed.

🔧 Check the template expression for syntax errors. Template expressions reference variables (e.g. {{variables.name}}) or stage outputs (e.g. {{stage.field}}); ensure the braces and field names are well-formed.

Code 15: Plex Errors

Component Already Exists (cal-plex-001)

🔍 A component with the same name or UUID already exists in the Plex.

🔧 Remove the existing component first, or use a different name/UUID for the new component.

Component Does Not Exist (cal-plex-002)

🔍 The specified component (by name or UUID) does not exist in the Plex.

🔧 Check for typos in the component name or UUID. Use metrical plex list to see all components in the Plex.

Constraint Already Exists (cal-plex-003)

🔍 A constraint between the specified component pair already exists in the Plex.

🔧 Remove the existing constraint first if you want to replace it with a new one.

Self-Constraint (cal-plex-004)

🔍 The "from" and "to" UUIDs of the constraint are the same. Constraints must connect two distinct components.

🔧 Ensure that the source and destination components of the constraint are different.

Non-Finite Constraint Values (cal-plex-005)

🔍 The constraint contains non-finite values (NaN or infinity) in its extrinsics.

🔧 Check that the translation and rotation values for this constraint are valid finite numbers.

Empty Formation (cal-plex-006)

🔍 The formation contains no components.

🔧 A formation must reference at least one component. Add components to the formation or remove the empty formation.

Ambiguous Component (cal-plex-007)

🔍 A component being added conflicts with two existing components that share either its name or UUID.

🔧 Modify the conflicting component so its UUID and name match exactly one of the existing components.

Missing Spatial Constraint (cal-plex-008)

🔍 There is no spatial constraint between the specified components.

🔧 Use metrical plex list to inspect the Plex's constraints.

Missing Temporal Constraint (cal-plex-009)

🔍 There is no temporal constraint between the specified components in the provided Plex.

🔧 Check that both components exist in the Plex and that a temporal constraint connects them. Use metrical plex list to inspect the Plex's constraints.

No Topics Found (cal-plex-010)

🔍 None of the requested topics were found or readable in the dataset.

🔧 Check that either the Plex passed to plex learn already has components for the topics in the dataset, or provide -m TOPIC:MODEL mappings for topics in the dataset.

No Data To Learn (cal-plex-011)

🔍 The application was not able to create a Plex from the init data.

🔧 This could be because: none of the requested topics exist in the dataset, the dataset is empty, or the requested topics are not in a format that MetriCal can read. Check the dataset and try again.

Impossible Image Resolution (cal-plex-012)

🔍 Last read image for a topic has a width or height of 0 pixels.

🔧 Check your image data to ensure that images have valid, non-zero dimensions. This may indicate corrupted image data or an issue with the image encoding.

Model and Data Mismatch (cal-plex-013)

🔍 The model kind provided via -m TOPIC:MODEL does not match the component kind inferred from the data streamed on that topic.

🔧 Try running the command again with a compatible model. Call plex learn --help for more information about which models are compatible with each component type.

Code 16: Spec Errors

Camera Link Not In URDF (cal-spec-001)

🔍 The camera link specified via --camera does not match any link in the URDF file.

🔧 Check for typos in the --camera link name. The link must exactly match a <link> element in the URDF. You can also use --remap to map URDF link names before applying --camera.

Remap Link Not In URDF (cal-spec-002)

🔍 The remap key specified via --remap OLD:NEW does not match any link in the URDF file.

🔧 Check for typos in the OLD part of the --remap argument. It must exactly match a <link> element in the URDF.

Duplicate Camera Link (cal-spec-003)

🔍 The same link name was specified in --camera more than once.

🔧 Each --camera link must be unique. Remove the duplicate entry.

Camera Link Not In Fixed Joint (cal-spec-004)

🔍 The camera link exists in the URDF but is not connected via a fixed joint.

🔧 Only links connected by fixed joints appear in the mechanical layout. The specified link exists in the URDF but has no fixed joint, so it cannot be used as a camera.

Duplicate Topic Name (cal-spec-005)

🔍 Multiple URDF links resolve to the same topic name after applying --strip-prefix, --topic-prefix, and --remap transforms.

🔧 Use --remap to give each colliding link a unique topic name.

Invalid Transform-Tree Frames Spec (cal-spec-010)

🔍 The provided --tf-frames specification is malformed.

🔧 Provide transform-tree frame specifications in the format BASE_FRAME:TOOL_FRAME:MOUNT_TYPE, where MOUNT_TYPE is either eye-to-hand or hand-in-eye. For example: --tf-frames base_link:tool0:eye-to-hand.