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

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.

License File Verification Failed (license-002)

🔍 Verifying the license-cache file failed.

🔧 Ensure a valid license-cache file exists at the specified path and has not been edited or corrupted. This error occurs when there's malformed JSON, missing/malformed JSON fields, or signature verification fails.

Could Not Read License File (license-004)

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

🔧 Ensure a license-cache file exists at the specified path and is readable. This is usually the result of a permissions error or the file does not exist.

Could Not Deserialize License File (license-005)

🔍 The license-cache file could not be parsed.

🔧 Ensure the license-cache file has not been edited or corrupted. This likely means the file was tampered with or the file was written by an old version of MetriCal without backwards-compatibility.

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.

🔧 Please contact support@tangramvision.com. Offline operation is not possible without a license-cache file. This occurs when $HOME is not set or the user doesn't have an entry in /etc/passwd.

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 the directory exists and that the program has write permissions. This is usually the result of a permissions error and may cause this machine to be counted more than once for billing/licensing purposes.

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 if issue persists. This should never happen unless there are bugs in the serialization code.

Cached License Expired (license-009)

🔍 The license-cache file is expired.

🔧 Run MetriCal with internet access 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.

Config Missing License (license-012)

🔍 Failed to find license key in TOML config file.

🔧 No item named "license" found; possibly a typo in the config file?

Config Malformed License (license-013)

🔍 License key in TOML config file is invalid.

🔧 License key must be a string with non-zero length.

Could Not Read Config File (license-014)

🔍 Failed to read TOML config file.

🔧 Ensure the file exists and is readable, or provide an alternate license key 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.

No Default Config File Path (license-016)

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

🔧 Please contact support@tangramvision.com. This occurs when $HOME is not set or the user doesn't have an entry in /etc/passwd.

Config Malformed TOML (license-017)

🔍 Config file is not valid TOML.

🔧 See documentation for an example of valid TOML. Check the TOML syntax and formatting in your config file.

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.

Insufficient Credits (license-019)

🔍 Your license has insufficient credits to calibrate the provided plex.

🔧 Purchase more credits at https://hub.tangramvision.com/. Check your license's credit balance and the expected calibration cost to determine how many additional credits you need.

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.

IMU Motion Profile Issues (cal-calibrate-010)

🔍 Motion profile issues detected for IMU.

🔧 The IMU motion profile analysis detected issues with the excitation of this IMU. Please review the detected issues and consider re-collecting data with improved motion characteristics.

If you would like to process the rest of this calibration, re-init the plex without this component and rerun the calibration.

LNS Motion Profile Issues (cal-calibrate-011)

🔍 Motion profile issues detected for LNS.

🔧 The LNS motion profile analysis detected issues with the trajectory of this LNS. Please review the detected issues and consider re-collecting data with improved motion characteristics.

If you would like to process the rest of this calibration, re-init the plex without this component and rerun the calibration.

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.

Object Space Construction Error (cal-rendering-008)

🔍 An error occurred during object space construction.

🔧 This is an error from the underlying object space construction system. Check that your object space definition is valid, all required parameters are provided, and that referenced resources (meshes, textures, etc.) are accessible.

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.

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