# Moose / Help / Troubleshooting Documentation – TypeScript

## Included Files
1. moose/help/troubleshooting/troubleshooting.mdx

## Troubleshooting

Source: moose/help/troubleshooting/troubleshooting.mdx

Troubleshooting for Moose

# 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

   ```bash
   # Find processes using ports
   lsof -i :4000-4002

   # Kill process by PID
   kill 

2. **Missing dependencies**
   - Solution: Ensure all dependencies are installed

   ```bash
   npm install
   ```

3. **Docker not running**
   - Solution: Start Docker Desktop or Docker daemon

   ```bash
   # 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

   ```bash filename="Terminal" copy
   moose logs
   ```

2. **Stream processing errors**
   - Solution: Check transform functions for errors

   ```bash filename="Terminal" copy
   moose logs --filter functions
   ```

3. **Database connectivity**
   - Solution: Verify database credentials in `.moose/config.toml`

```toml filename=".moose/config.toml" copy
[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

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

### Issue: Data transformations not working

1. **Transform function errors**
   - Solution: Debug transformation logic

   ```typescript
   // 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
     }
   });
   ```

## Database Issues

### Issue: Slow queries

1. **Missing or improper indexes**
   - Solution: Check orderByFields configuration

   ```typescript
   const table = new OlapTable("slow_table", {
     orderByFields: ["frequently_queried_field", "timestamp"]
   });
   ```

2. **Large result sets**
   - Solution: Add limits and pagination

   ```typescript
   // In query API
   const 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

   ```bash
   # Validate configuration
   moose validate --config
   ```

2. **Resource limitations**
   - Solution: Increase resource allocation

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

3. **Permission issues**
   - Solution: Verify service account permissions

   ```bash
   # 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:**
   ```sql
   DELETE FROM _MOOSE_STATE WHERE key = 'migration_lock';
   ```

3. **Verify it worked:**
   ```sql
   SELECT * FROM _MOOSE_STATE WHERE key = 'migration_lock';
   -- Should return no rows
   ```

The `_MOOSE_STATE` table uses ClickHouse's KeeperMap engine for distributed locking, ensuring only one migration runs at a time across multiple deployments.

## Getting Help

If you can't resolve an issue:

1. Ask for help on the [Moose community Slack channel](https://join.slack.com/t/moose-community/shared_invite/zt-2fjh5n3wz-cnOmM9Xe9DYAgQrNu8xKxg)
2. Search existing [GitHub issues](https://github.com/514-labs/moose/issues)
3. Open a new issue with:
   - Moose version (`moose --version`)
   - Error messages and logs
   - Steps to reproduce
   - Expected vs. actual behavior