Errors & 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 mode errors	Historical exit code, unused
6	MetriCalLicense	License related errors
7	Display mode errors	Historical exit code, unused
8	CalibrateMode	Calibrate related errors
9	Completion mode errors	Historical exit code, unused
10	Rendering	Rendering related errors
11	Consolidate object space errors	Historical exit code, unused
12	Diagnostic	A High-Level Diagnostic was thrown
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

This section contains information related to the various errors that can occur due to accessing the filesystem. Many of these issues may relate to the fact that MetriCal is often run inside of a Docker container. As such, be sure to check that the specific path related to the error is correctly mounted as a volume inside of MetriCal.

File Read Failure (cal-io-001)

🔍 Failed to locate any file at the provided path.

🔧 If you are operating MetriCal in a Docker instance, make sure you are using the mounted Docker work directory, not your $HOME or local paths.

Memory Map Failure (cal-io-002)

🔍 Failed to memory map the provided data set.

🔧 This usually would fail if you do not have read permissions on the file in question (usually an MCAP file).

Malformed MCAP (cal-io-003)

🔍 The MCAP file provided could not be read.

🔧 Usually this indicates that while the file path looks like an MCAP file, the file itself does not conform to the MCAP specification (see https://mcap.dev/spec), or is corrupt in some way.

Malformed ROSbag (cal-io-004)

🔍 The ROSbag file provided could not be read.

🔧 Similar to cal-io-003, the file path appears as a ROS 1 Bag v2.0, but does not conform to the ROS bag specification or is corrupt in some way.

Malformed Plex Or Results (cal-io-005)

🔍 The provided path, when read, was not recognized as a valid plex.

🔧 Acceptable files include either a self-contained plex or a MetriCal results file. See our schemata for the correct JSON Schema for plex files.

Malformed Object Space Or Results (cal-io-006)

🔍 The provided path, when read, was not recognized as a valid object space.

🔧 Acceptable files include either a self-contained object space or a MetriCal results file. See our schemata for the correct JSON Schema for object-space files.

Malformed Pipeline (cal-io-007)

🔍 The provided pipeline file is malformed.

🔧 If you need help structuring your pipeline JSON, log in debug mode (-v). The JSON for the current command will print to the console.

Invalid Seed Plex (cal-io-008)

🔍 The seed file provided could not be parsed as either a plex, results file, or URDF.

🔧 The file that was provided was not recognized as a valid plex, MetriCal results file, or ROS URDF. See our schemata for the correct JSON Schema for plex and result files, and check the ROS docs for whether or not you have a valid URDF.

Folder No Components (cal-io-009)

🔍 Failed to read any component folders in the data set.

🔧 Check your component names. Do they match your observation folder names?

Folder Filenames Not Timestamps (cal-io-010)

🔍 Failed to interpret any filenames in any folders as timestamps.

🔧 Observation filenames should be formatted in nanoseconds:

• ❌ camera_5.png
• ❌ 2022-01-26T12:02:33.906000000.png
• ✅ 1643230553906000000.png

Deserialize Failure (cal-io-011)

🔍 Failed to serialize a struct when reading in a file.

🔧 If this is a JSON file, make sure that you're not missing any commas. MetriCal can accept JSON with comments, so don't feel the need to modify your JSON heavily.

Serialize Failure (cal-io-012)

🔍 Failed to serialize data as JSON.

🔧 Check your JSON structure for any inconsistencies or errors.

Msgpack Failure (cal-io-013)

🔍 Failed to serialize tabular calibration as message pack.

🔧 This may indicate an issue with the calibration data format.

Write Failure (cal-io-014)

🔍 Failed to write file at path.

🔧 This error can often occur due to permissions errors in the path being written. Double check that your user has permission (and space left on the device) to write the file.

Cached Detections For Wrong Plex (cal-io-015)

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

🔧 This occurs when a plex has been changed or modified after detections have been cached for a particular data set. You can either verify that the UUIDs match the previous plex, or remove the cached detections and run MetriCal on the data anew.

URDF Conversion Error (cal-io-016)

🔍 Failed to convert Plex to URDF.

🔧 Check your plex configuration for compatibility with URDF format requirements.

Metadata Error (cal-io-017)

🔍 Failed to read metadata for file at a given path.

🔧 This error can occur for a number of reasons: either because the path is wrong, the inode for the file has been removed while querying for it, or because of some other block-device level fault in the system.

Code 2: CLI Errors

Missing Component (cal-cli-001)

🔍 There is no component with the provided name or UUID in the 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 Mappings (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.

🔧 Format this argument as key:value.

Invalid Coordinate Basis (cal-cli-005)

🔍 Failed to recognize coordinate basis. Bases must be orthonormal.

🔧 Valid bases contain the following short descriptors for a given orthonormal format:

• L for "Left"
• R for "Right"
• U for "Up"
• D for "Down"
• F for "Forward"
• B for "Backwards"

These are combined in 3-character combinations to produce a "basis" that MetriCal can use, mapping X, Y, and Z axes to each direction respectively. An example is to map positive X in the right direction, positive Y in the down direction, and positive Z in the forward direction. This forms a right-handed orthonormal basis, which we refer to as "RDF".

Unrecognized Model (cal-cli-006)

🔍 The provided model is not recognized by MetriCal.

🔧 MetriCal maps models to a given topic name dependent on the type of component that the topic's data represents. See the init documentation for more information.

Component Name Already Exists (cal-cli-007)

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

🔧 Ensure you're not trying to map a single topic to multiple components in the plex.

File Would Be Overwritten (cal-cli-008)

🔍 The file at the provided path will be overwritten, but the --overwrite (short: -y) flag was not provided.

🔧 Deleting the file at the path 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.

If you would like to instead preserve the UUID relations and overwrite the previous plex, pass the corresponding --overwrite flag (-y) for the specified command.

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.

🔧 Ensure that you passed in the correct plex, and double-check that the component UUIDs and names that you passed into the shape command do not have a typo.

Component Cannot Make LUT (cal-shape-002)

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

🔧 Look Up Tables (LUTs) are one way to accelerate the computation of distortion and rectification for the purposes of image projection and un-projection. Non-Camera components do not have an equivalent set of distortion parameters that can be used to generate a LUT. Make sure to double-check that the component you specified is a camera.

Bad Stereo Configuration (cal-shape-003)

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

🔧 In order for a stereo pair to be produced via the shape subcommand, both components need to have a spatial constraint between them. Make sure that you have run the calibrate command over the plex and that there exists some chain of spatial constraints between the two components. You can reference a component either by its name or UUID.

Code 4: Init Errors

Cannot Create Camera (cal-init-001)

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

🔧 Verify that the data format matches what's expected for camera components and that all required information is present in the dataset.

Cannot Create Lidar (cal-init-002)

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

🔧 Verify that the data format matches what's expected for lidar components and that all required information is present in the dataset.

Cannot Create IMU (cal-init-003)

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

🔧 Verify that the data format matches what's expected for IMU components and that all required information is present in the dataset.

Impossible Image Resolution (cal-init-004)

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

🔧 Make sure that your data has been written to the specified data format correctly and with the correct size and / or resolution.

Inconsistent Image Resolution (cal-init-005)

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

🔧 Make sure that your data has been written to the specified data format correctly and with the correct size and / or resolution.

No Topics Found (cal-init-006)

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

🔧 Check that the dataset contains the topics requested and that they are in a readable format.

Plex Already Exists (cal-init-007)

🔍 Previous Plex already exists at path.

🔧 Deleting this previous plex will trigger a fresh run of Init mode, but will also reset your UUIDs for each topic. This can cause some associations to become lost, like component relations in cached detections. If you would like to instead preserve the UUID relations and overwrite the previous plex, pass the --overwrite flag (-y) to Init mode.

No Data To Initialize (cal-init-008)

🔍 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.

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.

License File Verification Failed (license-002)

🔍 Verifying the license-cache file failed.

🔧 Ensure a valid license-cache file exists and has not been edited or corrupted. See the licensing setup instructions to enable offline licensing.

Could Not Read License File (license-004)

🔍 A license-cache file could not be read from disk.

🔧 Ensure a license-cache file exists and is readable. See the licensing setup instructions to enable offline licensing.

Could Not Deserialize License File (license-005)

🔍 The license-cache file could not be parsed.

🔧 Ensure a valid license-cache file exists and has not been edited or corrupted. See the licensing setup instructions to enable offline licensing.

No Default License File Path (license-006)

🔍 No default application config path could be found in order to locate or write the license-cache file.

🔧 This is likely an issue with Docker configuration causing the HOME environment variable to be unset inside the container. Please review and follow the licensing setup instructions to enable offline licensing. If the issue persists, contact support@tangramvision.com.

Could Not Write License File (license-007)

🔍 The license-cache file could not be written to disk.

🔧 Offline operation is not possible without a license-cache file. Ensure that the metrical-license-cache volume is being successfully mounted into the Docker container. Please review and follow the licensing setup instructions to enable offline licensing. If the issue persists, contact support@tangramvision.com.

Could Not Serialize License File (license-008)

🔍 The license-cache file could not be serialized to disk.

🔧 Offline operation is not possible without a license-cache file. Please contact us at support@tangramvision.com.

Cached License Expired (license-009)

🔍 The license-cache file is expired.

🔧 Run MetriCal with internet access to refresh the license. You must run a command/sub-command (other than help) in order to refresh the license.

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 with an active internet connection to regenerate the license-cache file.

Config Missing License (license-012)

🔍 Failed to find license key in TOML config file.

🔧 No item named "license" found in TOML config file. Please ensure there is a top-level key named "license" in the TOML config file. Please reference the licensing setup instructions for an example of how the TOML config file should look.

Config Malformed License (license-013)

🔍 License key in TOML config file is invalid.

🔧 License key found in TOML config file is malformed (i.e. it is not a string or it has a length of zero). Ensure the license key in the TOML config file is a non-empty string. Please reference the licensing setup instructions for an example of how the TOML config file should look.

Could Not Read Config File (license-014)

🔍 Failed to read TOML config file.

🔧 Ensure the file exists and is readable, or provide the license key via an alternative source (CLI argument, environment variable).

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. Please reference the licensing setup instructions for examples of how to use a license key with MetriCal.

No Default Config File Path (license-016)

🔍 No default application config path could be found in order to locate the config file.

🔧 This is likely an issue with Docker configuration causing the HOME environment variable to be unset inside the container. Please see the licensing setup instructions for an example of docker commands and options to use. If the issue persists, contact support@tangramvision.com.

Config Malformed TOML (license-017)

🔍 Config file is not valid TOML.

🔧 Ensure the config file is valid TOML. Please reference the licensing setup instructions for an example of how the TOML config file should look.

License API Error (license-018)

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

🔧 This could be due to network issues, API changes, or server-side problems. Please check your network connection and ensure you're using the latest version of MetriCal. If the issue persists, contact support@tangramvision.com with the specific error message.

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. Double check:

• The measurements of your fiducials. These should be in meters.
• 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 colinear, 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.

Detector Error (cal-calibrate-002)

🔍 There was an error when working with the detector.

🔧 This error is often unrecoverable, or a result of a misconfigured object-space file. Contact support@tangramvision.com if you need assistance in crafting the correct object-space file, or making modifications to an existing one.

Detector-Descriptor Error (cal-calibrate-003)

🔍 There was an error when working with the detector-descriptor.

🔧 This error is often unrecoverable, or a result of a misconfigured object-space file. Contact support@tangramvision.com if you need assistance in crafting the correct object-space file, or making modifications to an existing one.

Calibration Solver Error (cal-calibrate-004)

🔍 Failed to run calibration to completion.

🔧 There was an error in the calibration solver. This error is unrecoverable, and should not occur outside of beta or release-candidate (rc) builds of MetriCal. Contact support@tangramvision.com if this error can be repeatably triggered or continues to persist.

Calibration Interpretation Failure (cal-calibrate-005)

🔍 Failed to interpret the calibration solution.

🔧 There was an error in the calibration solver. This error is unrecoverable, and should not occur outside of beta or release-candidate (rc) builds of MetriCal. Contact support@tangramvision.com if this error can be repeatably triggered or continues to persist.

Too Many Component Observations Filtered (cal-calibrate-006)

🔍 Too many observations from the plex were filtered out by the motion filter.

🔧 There was too much motion in this dataset for this component. All observations were filtered out. The motion filter will get rid of observations with detection changes over a certain metric threshold. This ensures that only data without motion artifacts gets used in a calibration.

• Before disabling the motion filter entirely (--disable-motion-filter), we recommend modifying your data capture process to incorporate pauses in motion every second or two.
• When calibrating IMU (which requires motion), raise the camera's motion filter threshold.

No Compatible Component Type to Register Against (cal-calibrate-007)

🔍 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 Type Has No Detections (cal-calibrate-008)

🔍 This data had a compabile 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 Type Has All Detections Filtered (cal-calibrate-009)

🔍 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 Optimization Failed (cal-calibrate-010)

🔍 The initial camera pose optimization for a component 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.

Could Not Report Successful Calibration (cal-calibrate-011)

🔍 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.

Code 10: Rendering Errors

Missing Recording Stream (cal-rendering-001)

🔍 No global Rerun connection found.

🔧 Ensure that a global Rerun connection is established before calling this function by calling set_global_recording_stream.

Log Failure (cal-rendering-002)

🔍 Could not log to Rerun.

🔧 This indicates an issue with the Rerun logging system. Check that Rerun is properly initialized and that the connection hasn't been interrupted.

Observation Incompatible (cal-rendering-003)

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

🔧 Check that you're using the correct render function for the type of observation you're working with. Each render function expects a specific observation type.

Missing Intrinsics (cal-rendering-004)

🔍 There were no intrinsics assigned to the image to be rendered.

🔧 All images should be pre-corrected before passing them to the render function. Make sure you've assigned the necessary intrinsic parameters to the image.

Empty Object Space (cal-rendering-005)

🔍 This object space is empty of renderable objects.

🔧 The object space you're trying to render doesn't contain any objects that can be displayed. Check your object space configuration to ensure it contains valid renderable elements.

Missing Component (cal-rendering-006)

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

🔧 Verify that the component name you're trying to render exists in your plex configuration. Check for typos or make sure the component has been properly initialized in the plex.

Recording Stream Error (cal-rendering-007)

🔍 An error occurred in the Rerun recording stream.

🔧 This indicates an underlying issue with the Rerun system. Check that Rerun is properly installed, running, and that your MetriCal Docker container has access to it.

Image Conversion Error (cal-rendering-008)

🔍 An error occurred during image conversion for rendering.

🔧 There was a problem converting or processing an image for rendering in Rerun. Check that your image formats are supported and that the image data is valid.

Object Space Construction Error (cal-rendering-009)

🔍 There was an error constructing the object space for rendering.

🔧 This error indicates a problem with the object space definition when preparing it for visualization. Check your object space configuration for any issues with the geometry or structure.

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.