Troubleshooting

This guide explains how undatum handles errors and provides troubleshooting tips for common issues.

Overview

undatum provides user-friendly error messages instead of raw Python tracebacks. All errors are categorized and include actionable guidance to help you resolve issues quickly.

Error Categories

Exit Code 1: User Errors

Errors caused by invalid input or user mistakes:

File not found
Invalid file format
Missing required parameters
Invalid field names
Query syntax errors

Exit Code 2: Configuration Errors

Errors related to configuration or dependencies:

Missing optional dependencies
Invalid configuration files
Missing environment variables

Exit Code 3: System Errors

Errors related to system resources or permissions:

Permission denied
Database connection errors
Network errors

Exit Code 4: Internal Errors

Unexpected errors that may indicate a bug:

Unhandled exceptions
Internal processing errors

Exit Code 130: Interrupted

The command was stopped with Ctrl-C (SIGINT). Output files are written to a temporary name and renamed only on success, so an interrupted command leaves no partial output.

Summary

Code	Meaning
0	Success
1	User error: missing file, invalid parameter, unsupported or non-writable format
2	Invalid command-line usage (unknown option, bad choice), configuration error, or missing optional dependency (install the named extra)
3	System error: permission denied, database or network failure
4	Internal error (please report it with the `--verbose` output)
130	Interrupted with Ctrl-C

A command never exits with 0 after reporting an error, so scripts can rely on $?.

Common Error Messages

File Not Found

Error:

Error: File not found: '/path/to/data.csv'
Did you mean: '/path/to/data2.csv'?
Check that the file path is correct and the file exists.

Solutions:

Verify the file path is correct
Check for typos in the filename
Use absolute paths if relative paths don't work
Ensure the file exists in the specified location

Example:

# Wrong
undatum convert data.cvs output.jsonl

# Correct (if typo detected, undatum suggests the correct file)
undatum convert data.csv output.jsonl

Permission Denied

Error:

Error: Permission denied: Cannot read '/path/to/data.csv'
Fix: chmod +r /path/to/data.csv
Or check file ownership and permissions.

Solutions:

Check file permissions: ls -l /path/to/data.csv
Add read permission: chmod +r /path/to/data.csv
Add write permission (for output files): chmod +w /path/to/output.csv
Check file ownership if you don't have permission to modify

Example:

# Fix read permission
chmod +r data.csv
undatum convert data.csv output.jsonl

# Fix write permission for output
chmod +w output.jsonl

Unsupported File Format

Error:

Error: Unsupported file format: 'xyz'
Supported formats: csv, jsonl, parquet, avro, orc, xml, xls, xlsx, bson
Use 'undatum convert' to convert to a supported format.

Solutions:

Convert the file to a supported format first
Check the file extension matches the actual format
Use --format-in to explicitly specify the format

Example:

# Convert unsupported format to CSV first
undatum convert input.xyz output.csv --format-in csv

Missing Required Parameter

Error:

Error: Invalid input: Missing required parameter 'fields'
The 'fields' option is required for this operation.

Solutions:

Check command documentation: undatum <command> --help
Provide all required parameters
Verify parameter names are correct

Example:

# Wrong - missing --fields
undatum select data.csv

# Correct
undatum select data.csv --fields name,email

Invalid Field Name

Error:

Error: Invalid parameter 'field_name': Field does not exist
Did you mean: 'field_name2'?
Valid options: field1, field2, field3

Solutions:

Check available fields: undatum headers data.csv
Use the suggested field name if a typo is detected
Verify field names match exactly (case-sensitive)

Example:

# Check available fields first
undatum headers data.csv

# Use correct field name
undatum select data.csv --fields email,phone

Missing Dependency

Error:

Error: Missing dependency: 'package_name'
This feature requires 'package_name'. Install it with:
  pip install package_name

Solutions:

Install the required dependency
Use the suggested installation command
For optional features, install extras: pip install undatum[api]

Example:

# Install missing dependency
pip install pyyaml

# Or install with extras
pip install "undatum[api]"

Database Connection Error

Error:

Error: Database error: Connection failed
postgresql error: Could not connect to database
Check connection URI and database server status.

Solutions:

Verify the database server is running
Check connection URI format
Verify credentials are correct
Check network connectivity
Ensure database exists

Example:

# Connection string format: scheme://user:password@host:port/database
undatum db load data.csv --db "postgresql://user:password@host:5432/dbname" --table users

Verbose Mode

For detailed error information including full tracebacks, use the --verbose flag:

undatum convert data.csv output.jsonl --verbose

This is useful for:

Debugging internal errors
Reporting bugs
Understanding the full error context

Error Message Features

Typo Detection

undatum automatically detects typos in file paths and field names:

# Typo in filename - undatum suggests corrections
undatum convert data.cvs output.jsonl
# Error: File not found: 'data.cvs'
# Did you mean: 'data.csv'?

Actionable Guidance

All error messages include specific steps to resolve the issue:

Permission errors include chmod commands
Format errors list supported formats
Dependency errors include installation commands
Field errors suggest valid alternatives

Consistent Formatting

All errors follow a consistent format:

Error: <Error type>: <Description>
<Actionable guidance>