Common Errors
Troubleshoot common GoMask CLI errors
Common Errors
Solutions for frequently encountered GoMask CLI errors.
Authentication Errors
"Authentication required"
Cause: CLI is not configured with API credentials.
Solution:
# Initialize with your API secret
gomask init
Get your API secret from datafactory.gomask.ai/settings/api-keys.
"Invalid API secret"
Cause: The API secret is incorrect or expired.
Solution:
- Verify your secret at datafactory.gomask.ai/settings/api-keys
- Generate a new key if needed
- Reinitialize:
gomask init --force
"Permission denied reading gomask.toml"
Cause: File permissions are too restrictive.
Solution:
chmod 600 gomask.toml
Connection Errors
"Unable to connect to database"
Cause: Database connection failed.
Solutions:
- Test the connection:
gomask connectors test my-connector
- Verify connection details:
gomask connectors show my-connector
- Check network connectivity:
# For PostgreSQL
pg_isready -h hostname -p 5432
- Verify firewall/security group rules
"Connection refused"
Cause: Database server is not accepting connections.
Solutions:
- Verify the database is running
- Check the port number
- Ensure the host is correct (localhost vs. actual hostname)
- Check if SSL is required
gomask connectors create \
--name my-db \
--type postgresql \
--host localhost \
--port 5432 \
--database mydb \
--username user \
--ssl-mode require
"Connector not found"
Cause: The referenced connector doesn't exist.
Solutions:
- List available connectors:
gomask connectors list
- Check the connector_id in your YAML:
routine:
connector_id: 1 # Use ID from 'gomask connectors list'
Validation Errors
"Invalid YAML syntax"
Cause: YAML file has syntax errors.
Solutions:
-
Check for common issues:
- Missing colons after keys
- Incorrect indentation (use spaces, not tabs)
- Unclosed quotes
-
Validate with detailed output:
gomask validate routine.yaml --detailed
"Required field missing"
Cause: A required field is not present.
Example error:
Error: routine.name is required
Solution: Add the missing field:
routine:
name: "My Routine" # Required
type: synthetic # Required: synthetic or masking
connector_id: 1 # Required
"Unknown function"
Cause: The specified function doesn't exist.
Solutions:
- List available functions:
gomask functions list --search function_name
- Check spelling and use exact function names:
columns:
- column_name: email
generation_function: generate_email # Correct
"Environment variable not set"
Cause: A required environment variable is missing.
Example error:
Error: Environment variable DB_PASSWORD is required but not set
Message: Database password required
Solutions:
- Set the variable:
export DB_PASSWORD="your-password"
- Or use a .env file:
gomask validate routine.yaml --env-file .env
- Or provide a default in YAML:
password: ${DB_PASSWORD:-default_value}
Execution Errors
"Foreign key violation"
Cause: Child records reference non-existent parent records.
Solutions:
- Check hierarchy levels - parents must be lower:
tables:
- table_name: customers
hierarchy_level: 0 # Parent - generates first
- table_name: orders
hierarchy_level: 1 # Child - generates after
-
Ensure parent tables are included in the routine
-
Configure foreign key columns correctly:
columns:
- column_name: customer_id
is_foreign_key: true
referenced_table: customers
referenced_column: id
"Table not found"
Cause: The specified table doesn't exist in the database.
Solutions:
- Verify table exists with correct schema:
tables:
- table_name: users
schema_name: public # Check schema name
- Check case sensitivity (PostgreSQL is case-sensitive for quoted identifiers)
"Column not found"
Cause: The specified column doesn't exist.
Solutions:
- Verify column name matches database exactly
- Check for typos
- Verify the column hasn't been renamed
"Execution timeout"
Cause: Execution exceeded the timeout limit.
Solutions:
- Increase timeout:
gomask run routine.yaml --timeout 7200 # 2 hours
- Reduce record count
- Split into smaller routines
"Out of memory"
Cause: Too many records being processed.
Solutions:
- Reduce batch size:
settings:
batch_size: 500 # Smaller batches
- Reduce record count
- Run tables separately
Import/Export Errors
"Routine already exists"
Cause: A routine with the same unique_id already exists.
Solutions:
- Update the existing routine:
gomask import routine.yaml --update
- Or change the unique_id in your YAML
"Export failed: Routine not found"
Cause: The specified routine doesn't exist.
Solutions:
- List available routines:
gomask routines list
- Use correct identifier (ID or unique_id):
gomask export 123 # By numeric ID
gomask export my-routine-id # By unique_id
Getting Help
Enable Debug Mode
For more detailed error information:
export GOMASK_DEBUG=true
gomask run routine.yaml
Check Execution Logs
gomask executions show <execution-id> --logs
Contact Support
- Email: [email protected]
- Documentation: docs.gomask.ai