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
   Terminal

   Copy code

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

   Configuration Override: You can also change the ports Moose uses via environment variables:

   Terminal

   Copy code

   export MOOSE_HTTP_PORT=4040
   export MOOSE_MANAGEMENT_PORT=5010
   moose dev

2. Missing dependencies

   • Solution: Ensure all dependencies are installed
   TypeScriptPython

   Terminal

   Copy code

   npm install

3. Docker not running

   • Solution: Start Docker Desktop or Docker daemon
   Terminal

   Copy code

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

4. Container Startup Failures

   • Check if specific containers failed to start.
   • Solution: View container logs to debug service-specific issues.
   Terminal

   Copy code

   # View logs
   moose logs

Data Ingestion

Issue: Data not appearing in tables

1. Validation errors

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

   Copy code

   moose logs

2. Stream processing errors

   • Solution: Check transform functions for errors
   Terminal

   Copy code

   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 = falsehost = "localhost"host_port = 18123native_port = 9000

Stream Processing

Issue: High processing latency

1. Insufficient parallelism

   • Solution: Increase stream parallelism
   TypeScriptPython

   Copy code

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

Issue: Data transformations not working

1. Transform function errors

   • Solution: Debug transformation logic
   TypeScriptPython

   Copy code

   // Add logging to transformstream.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  }});

Database Issues

Issue: Slow queries

1. Missing or improper indexes

   • Solution: Check orderByFields configuration
   TypeScriptPython

   Copy code

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

2. Large result sets

   • Solution: Add limits and pagination
   TypeScriptPython

   Copy code

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

Deployment Issues

Issue: Deployment fails

1. Configuration errors

   • Solution: Check deployment configuration
   Terminal

   Copy code

   # Validate configuration
   moose validate --config

2. Resource limitations

   • Solution: Increase resource allocation
   Copy code

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

3. Permission issues

   • Solution: Verify service account permissions
   Terminal

   Copy code

   # Check permissions
   moose auth check

Issue: Migration stuck with "Migration already in progress"

Cause: A previous migration was interrupted without releasing its lock.

Solution:

1. Wait 5 minutes - locks expire automatically

2. Or manually clear the lock:

   Copy code

   DELETE FROM _MOOSE_STATE WHERE key = 'migration_lock';

3. Verify it worked:

   Copy code

   SELECT * FROM _MOOSE_STATE WHERE key = 'migration_lock';-- Should return no rows

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