Common Errors & Troubleshooting

This guide covers the most common errors you might encounter when using Dataspine and how to resolve them.

Authentication & Authorization Errors

Error: `Invalid API key`

Symptoms:

Error: Authentication failed: Invalid API key
HTTP 401: Unauthorized

Causes & Solutions:

Expired API Key

# Generate a new API key
dataspine auth refresh-key

# Update your environment
export DATASPINE_API_KEY="new-key-here"

Wrong Organization

# Check your current configuration
dataspine config show

# Set the correct organization
dataspine config set organization "correct-org-name"

Key Permissions

# Check key permissions
dataspine auth whoami

# Request additional permissions if needed
dataspine auth request-access --resource "data-products" --action "create"

Error: `Insufficient permissions`

Symptoms:

Error: Access denied: Insufficient permissions for action 'deploy'
HTTP 403: Forbidden

Solutions:

# Check your current permissions
dataspine auth permissions

# Contact your organization admin to grant permissions
dataspine auth request-access \
  --resource "data-products" \
  --action "deploy" \
  --justification "Need to deploy customer analytics data product"

Data Product Errors

Error: `Schema validation failed`

Symptoms:

Error: Schema validation failed
- Field 'customer_id' is required but missing
- Field 'email' format is invalid

Solutions:

Check Schema Definition

// Fix schema/outlets/customers.json
{
  "type": "object",
  "properties": {
    "customer_id": {
      "type": "string",
      "format": "uuid"
    },
    "email": {
      "type": "string",
      "format": "email"
    }
  },
  "required": ["customer_id", "email"]
}

Validate Schema

# Validate your schema files
dataspine schema validate --all

# Test with sample data
dataspine schema test --schema customers --data test_data.json

Error: `Transformation compilation failed`

Symptoms:

Error: Failed to compile transformation 'process_orders'
- Missing import: 'serde::Serialize'
- Undefined function: 'calculate_total'

Solutions:

Check Rust Dependencies

// Add missing imports
use serde::{Deserialize, Serialize};
use chrono::{DateTime, Utc};

// Ensure all functions are defined
fn calculate_total(items: &[OrderItem]) -> f64 {
    items.iter().map(|item| item.price * item.quantity as f64).sum()
}

Test Compilation Locally

# Test compilation
dataspine build --transformation process_orders

# Run unit tests
dataspine test --unit

Error: `Data source connection failed`

Symptoms:

Error: Failed to connect to data source 'customer_database'
- Connection timeout after 30 seconds
- Host 'db.internal.company.com' not reachable

Solutions:

Check Network Connectivity

# Test connectivity from Dataspine environment
dataspine network test --target db.internal.company.com:5432

# Check firewall rules
dataspine network check-firewall --source dataspine --target customer_database

Verify Credentials

# Test database credentials
dataspine sources test-connection customer_database

# Update credentials if needed
dataspine sources update-credentials customer_database \
  --username new_user \
  --password-from-env DB_PASSWORD

Check Configuration

# dataspine.yaml
ingests:
  - name: customers
    type: postgresql_cdc
    source: customer_database
    config:
      host: db.internal.company.com  # Verify this is correct
      port: 5432
      database: customer_db
      ssl_mode: require

Deployment Errors

Error: `Deployment validation failed`

Symptoms:

Error: Deployment validation failed
- Data product 'customer-analytics' version 1.2.0 incompatible with existing version 1.1.0
- Breaking schema change detected in 'customer_profile'

Solutions:

Check Schema Compatibility

# Check compatibility
dataspine schema check-compatibility \
  --current 1.1.0 \
  --proposed 1.2.0

# Generate migration script
dataspine schema generate-migration \
  --from 1.1.0 \
  --to 1.2.0

Use Versioning Strategy

# Mark breaking changes explicitly
version: 2.0.0  # Major version bump for breaking changes
migration:
  backward_compatible: false
  migration_scripts:
    - migrate_v1_to_v2.sql

Error: `Resource limits exceeded`

Symptoms:

Error: Deployment failed: Resource limits exceeded
- CPU usage: 95% (limit: 90%)
- Memory usage: 8.5GB (limit: 8GB)

Solutions:

Increase Resource Limits

# dataspine.yaml
resources:
  cpu: "2"
  memory: "16Gi"
  
# Or use auto-scaling
scaling:
  enabled: true
  min_replicas: 2
  max_replicas: 10
  target_cpu_percentage: 70

Optimize Performance

# Analyze resource usage
dataspine metrics analyze customer-analytics --resource-usage

# Get optimization recommendations
dataspine optimize recommend customer-analytics

Data Quality Issues

Error: `Data quality threshold not met`

Symptoms:

Error: Data quality check failed
- Completeness: 85% (threshold: 95%)
- Uniqueness: 92% (threshold: 99%)
- 1,234 duplicate customer_ids found

Solutions:

Add Data Quality Rules

# Add to dataspine.yaml
quality_rules:
  - name: customer_id_unique
    field: customer_id
    rule: unique()
    action: reject
    
  - name: email_format
    field: email
    rule: regex("^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$")
    action: warn

Implement Data Cleaning

// Add data cleaning transformation
#[transformation]
pub fn clean_customer_data(
    input: InputStream<RawCustomer>
) -> OutputStream<CleanCustomer> {
    input
        .filter(|customer| !customer.email.is_empty())
        .dedup_by(|customer| customer.customer_id.clone())
        .map(|customer| CleanCustomer {
            customer_id: customer.customer_id,
            email: customer.email.to_lowercase().trim().to_string(),
            // ... other fields
        })
        .into()
}

Error: `Data freshness SLA violated`

Symptoms:

Warning: Data freshness SLA violated
- Latest data age: 8 minutes (SLA: 5 minutes)
- Last successful ingestion: 2024-01-15 14:23:15 UTC

Solutions:

Check Ingestion Pipeline

# Check pipeline status
dataspine status customer-analytics --ingestion

# View ingestion logs
dataspine logs customer-analytics --component ingestion --follow

Tune Ingestion Settings

# Increase ingestion frequency
ingests:
  - name: customers
    config:
      polling_interval: 30s  # Reduced from 60s
      batch_size: 1000       # Increased from 500
      parallelism: 4         # Increased from 2

Performance Issues

Error: `Query timeout`

Symptoms:

Error: Query timeout after 30 seconds
API call to /api/v1/customer-analytics/customers failed

Solutions:

Optimize Queries

# Analyze query performance
dataspine metrics query-performance customer-analytics

# Add indexes
dataspine index create customer-analytics \
  --field customer_id \
  --field created_at

Use Caching

# Enable caching
outlets:
  - name: customers
    type: api
    config:
      cache_enabled: true
      cache_ttl: 300  # 5 minutes
      cache_size: 1000

Pagination and Filtering

# Use pagination for large datasets
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.dataspine.io/v1/customer-analytics/customers?limit=100&offset=0"

# Apply filters to reduce data
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.dataspine.io/v1/customer-analytics/customers?status=active&created_after=2024-01-01"

Error: `Memory usage exceeded`

Symptoms:

Error: OutOfMemoryError in transformation 'aggregate_customer_metrics'
Container killed due to memory limit (8GB)

Solutions:

Optimize Memory Usage

// Use streaming aggregation instead of collecting all data
#[transformation]
pub fn aggregate_customer_metrics(
    input: InputStream<CustomerEvent>
) -> OutputStream<CustomerMetrics> {
    input
        .key_by(|event| event.customer_id.clone())
        .window(TumblingWindow::of(Duration::hours(1)))
        .aggregate(CustomerMetricsState::new(), |state, event| {
            state.add_event(event);  // Incremental aggregation
            state.get_metrics()
        })
        .into()
}

Increase Memory Limits

# dataspine.yaml
resources:
  memory: "16Gi"  # Increased from 8Gi
  
# Or enable memory-optimized processing
processing:
  memory_optimized: true
  spill_to_disk: true

Network & Connectivity Issues

Error: `Service unavailable`

Symptoms:

Error: Service unavailable (HTTP 503)
Unable to reach Dataspine API at https://api.dataspine.io

Solutions:

Check Service Status

# Check Dataspine status page
curl https://status.dataspine.io/api/v2/status.json

# Or visit https://status.dataspine.io

Test Network Connectivity

# Test DNS resolution
nslookup api.dataspine.io

# Test connectivity
curl -I https://api.dataspine.io/health

# Check proxy settings
echo $HTTP_PROXY
echo $HTTPS_PROXY

Use Alternative Endpoints

# Try different region endpoint
dataspine config set api-endpoint https://eu-central-1.api.dataspine.io

CLI Issues

Error: `Command not found: dataspine`

Symptoms:

bash: dataspine: command not found

Solutions:

Check Installation

# Verify installation path
which dataspine

# Check PATH
echo $PATH

# Add to PATH if needed
export PATH="/usr/local/bin:$PATH"

# Make permanent (add to ~/.bashrc or ~/.zshrc)
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc

Reinstall CLI Download the latest release from GitHub Releases and re-run the installer:
```
tar xzf dataspine-*.tar.gz && cd dataspine && ./install.sh --update
```

Error: `Config file corrupted`

Symptoms:

Error: Failed to parse config file ~/.dataspine/config.yaml
yaml: line 5: mapping values are not allowed in this context

Solutions:

Reset Configuration

# Backup current config
cp ~/.dataspine/config.yaml ~/.dataspine/config.yaml.backup

# Reset to defaults
dataspine config reset

# Reconfigure
dataspine auth login
dataspine config set organization "your-org"

Fix YAML Syntax

# Check YAML syntax
current_context: "production"  # Ensure quotes are properly closed

contexts:
  development:
    organization: "my-org"
    environment: "dev"

Getting More Help

Enable Debug Logging

# Enable verbose logging
export DATASPINE_LOG_LEVEL=debug

# Run command with detailed output
dataspine deploy --verbose --debug

# Save logs to file
dataspine deploy --debug 2>&1 | tee debug.log

Collect Diagnostic Information

# Generate diagnostic report
dataspine diagnostic collect

# This creates a diagnostic bundle with:
# - Configuration files
# - Recent logs
# - System information
# - Network connectivity tests

Contact Support

When contacting support, please include:

Error message (complete error output)
Command that failed (exact command and arguments)
Environment information (dataspine version, OS, etc.)
Diagnostic bundle (if possible)

Support Channels:

📧 Email: support@dataspine.io
💼 LinkedIn: Dataspine on LinkedIn
🎫 Support Portal: support.dataspine.io
🐛 GitHub Issues: Report bugs

Error Code Reference

Code	Error	Category	Action
DS001	Invalid API Key	Auth	Check API key and permissions
DS002	Insufficient Permissions	Auth	Request access from admin
DS101	Schema Validation Failed	Data	Fix schema definition
DS102	Transformation Failed	Data	Check transformation code
DS201	Deployment Failed	Deploy	Check resources and compatibility
DS202	Health Check Failed	Deploy	Verify service configuration
DS301	Query Timeout	Performance	Optimize query or increase timeout
DS302	Memory Exceeded	Performance	Increase memory or optimize code
DS401	Service Unavailable	Network	Check service status and connectivity
DS402	Connection Timeout	Network	Check network and firewall settings

Authentication & Authorization Errors​

Error: Invalid API key​

Error: Insufficient permissions​

Data Product Errors​

Error: Schema validation failed​

Error: Transformation compilation failed​

Error: Data source connection failed​

Deployment Errors​

Error: Deployment validation failed​

Error: Resource limits exceeded​

Data Quality Issues​

Error: Data quality threshold not met​

Error: Data freshness SLA violated​

Performance Issues​

Error: Query timeout​

Error: Memory usage exceeded​

Network & Connectivity Issues​

Error: Service unavailable​

CLI Issues​

Error: Command not found: dataspine​

Error: Config file corrupted​

Getting More Help​

Enable Debug Logging​

Collect Diagnostic Information​

Contact Support​

Error Code Reference​

Authentication & Authorization Errors

Error: `Invalid API key`

Error: `Insufficient permissions`

Data Product Errors

Error: `Schema validation failed`

Error: `Transformation compilation failed`

Error: `Data source connection failed`

Deployment Errors

Error: `Deployment validation failed`

Error: `Resource limits exceeded`

Data Quality Issues

Error: `Data quality threshold not met`

Error: `Data freshness SLA violated`

Performance Issues

Error: `Query timeout`

Error: `Memory usage exceeded`

Network & Connectivity Issues

Error: `Service unavailable`

CLI Issues

Error: `Command not found: dataspine`

Error: `Config file corrupted`

Getting More Help

Enable Debug Logging

Collect Diagnostic Information

Contact Support

Error Code Reference