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

   pip 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

Stream Processing

Issue: High processing latency

1. Insufficient parallelism

   • Solution: Increase stream parallelism
   TypeScriptPython

   Copy code

   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
   TypeScriptPython

   Copy code

   # Add logging to transformdef 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
   TypeScriptPython

   Copy code

   from moose_lib import OlapTable, OlapConfig table = OlapTable[Data]("slow_table", OlapConfig(    order_by_fields=["frequently_queried_field", "timestamp"]))

2. Large result sets

   • Solution: Add limits and pagination
   TypeScriptPython

   Copy code

   # In query APIresults = client.query.execute(  # not an f-string, the values are provided in the dict  """  SELECT * FROM large_table  WHERE category = {category}  LIMIT {limit}  """, {"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