Troubleshooting

Common issues and their solutions when working with Moose.

Development Environment

Issue: moose dev fails to start

Possible causes and solutions:

1. Port conflicts

   • Check if ports 4000-4002 are already in use
   • Solution: Kill the conflicting processes or configure different ports

   # Find processes using ports
   lsof -i :4000-4002
    
   # Kill process by PID
   kill <PID>
    
    

2. Missing dependencies

   • Solution: Ensure all dependencies are installed

   npm install

   pip install .

3. Docker not running

   • Solution: Start Docker Desktop or Docker daemon

   # Check Docker status
   docker info
    
   # Start Docker on Linux
   sudo systemctl start docker

Data Ingestion

Issue: Data not appearing in tables

1. Validation errors

   • Check logs for validation failures
   • Solution: Ensure data matches schema
   Terminal

   moose logs

2. Stream processing errors

   • Solution: Check transform functions for errors
   Terminal

   moose logs --filter functions

3. Database connectivity

   • Solution: Verify database credentials in .moose/config.toml

[clickhouse_config]
db_name = "local"
user = "panda"
password = "pandapass"
use_ssl = false
host = "localhost"
host_port = 18123
native_port = 9000

Stream Processing

Issue: High processing latency

1. Insufficient parallelism

   • Solution: Increase stream parallelism

   const stream = new Stream<Data>("high_volume", {
     parallelism: 8  // Increase from default
   });

   from moose_lib import Stream, StreamConfig
    
   stream = Stream[Data]("high_volume", StreamConfig(parallelism=8) )

Issue: Data transformations not working

1. Transform function errors

   • Solution: Debug transformation logic

   // Add logging to transform
   stream.addTransform(outputStream, (record) => {
     console.log('Processing record:', record.id);
     try {
       // Your transformation logic
       return transformedRecord;
     } catch (error) {
       console.error('Transform error:', error);
       return undefined;  // Skip record on error
     }
   });

   # Add logging to transform
   def transform(record: Data) -> Data:
       print(f"Processing record: {record.id}")
       try:
           # Your transformation logic
           return transformed_record   
       except Exception as e:
           print(f"Transform error: {e}")
           return None  # Skip record on error        

Database Issues

Issue: Slow queries

1. Missing or improper indexes

   • Solution: Check orderByFields configuration

   const table = new OlapTable<Data>("slow_table", {
     orderByFields: ["frequently_queried_field", "timestamp"]
   });

2. Large result sets

   • Solution: Add limits and pagination

   // In query API
   const results = await client.query.execute(sql`
     SELECT * FROM large_table
     WHERE category = 'example'
     LIMIT 100
   `);

   # In query API
   results = client.query.execute(f"""
     SELECT * FROM large_table
     WHERE category = 'example'
     LIMIT 100
   """)

Deployment Issues

Issue: Deployment fails

1. Configuration errors

   • Solution: Check deployment configuration

   # Validate configuration
   moose validate --config

2. Resource limitations

   • Solution: Increase resource allocation

   # In kubernetes manifest
   resources:
     requests:
       memory: "1Gi"
       cpu: "500m"
     limits:
       memory: "2Gi"
       cpu: "1000m"

3. Permission issues

   • Solution: Verify service account permissions

   # Check permissions
   moose auth check

Getting Help

If you can’t resolve an issue:

1. Ask for help on the Moose community Slack channel
2. Search existing GitHub issues
3. Open a new issue with:
   • Moose version (moose --version)
   • Error messages and logs
   • Steps to reproduce
   • Expected vs. actual behavior