# Troubleshooting

## Containers have started but the application is not working

You can try resetting the volume storage by deleting the previously created volumes:

**Note that this step does not apply when you are setting up the application for the first time.**

```bash
source setup.sh --clean-data
```

## Search returns no results after changing embedding model

**Problem**: The UI displays `No videos found matching your search query. Try using different keywords or check if videos have been uploaded.` even though videos were ingested in `--search` or `--all` mode.

**Cause**: Either no videos have been processed yet, or the embedding model was switched to one with a different embedding dimension. Previously indexed vectors stay in the database, and their dimensions must match the active model. A mismatch prevents similarity lookups from returning any results.

**Solution**:

1. Verify at least one video has been uploaded or a summary run completed after the model change.
2. If you recently changed `EMBEDDING_MODEL_NAME`, re-run ingestion so embeddings are recreated with the new dimensions. You can clean existing data with `source setup.sh --clean-data` and then re-run your desired mode.
3. Review the supported embedding models and their dimensions in [microservices/multimodal-embedding-serving/docs/user-guide/supported-models.md](../../../../microservices/multimodal-embedding-serving/docs/user-guide/supported-models.md) before switching models.

## VLM Microservice Model Loading Issues

**Problem**: VLM microservice fails to load or save models with permission errors, or you see errors related to model access in the logs.

**Cause**: This issue occurs when the `ov-models` Docker volume was created with incorrect ownership (root user) in previous versions of the application. The VLM microservice runs as a non-root user and requires proper permissions to read/write models.

**Symptoms**:

- VLM microservice container fails to start or crashes during model loading
- Permission denied errors in VLM service logs
- Model conversion or caching failures
- Error messages mentioning `/home/appuser/.cache/huggingface` or `/app/ov-model` access issues

**Solution**:

1. Stop the running application:

   ```bash
   source setup.sh --down
   ```

2. Remove the existing `ov-models` (old volume name) and `docker_ov-models` (updated volume name) Docker volume:

   ```bash
   docker volume rm ov-models docker_ov-models
   ```

3. Restart the application (the volume will be recreated with correct permissions):

   ```bash
   # For Video Summarization
   source setup.sh --summary

   # Or for Video Search
   source setup.sh --search
   ```

> Note: Removing the `ov-models` or `docker_ov-models` volume will delete any previously cached or converted models. The VLM service will automatically re-download and convert models on the next startup, which may take additional time depending on your internet connection and the model size.

**Prevention**: This issue has been fixed in the current version of the VLM microservice Dockerfile. New installations will automatically create the volume with correct permissions.

## VLM Final Summary Hallucination Issues

**Problem**: The final summary generated by the VLM microservice contains hallucinated or inaccurate information that doesn't reflect the actual video content.

**Cause**: This issue can occur when using smaller VLM models that may not have sufficient capacity to accurately process and summarize complex video content, leading to generation of plausible but incorrect information.

**Symptoms**:

- The final summary contains information not present in the video
- The Summary describes events, objects, or activities that don't actually occur in the video
- Inconsistent or contradictory information in the generated summary
- The Summary quality is poor despite chunk-wise summaries being accurate

**Solution**:
Try using a larger, more capable VLM model by updating the `VLM_MODEL_NAME` environment variable:

1. Stop the running application:

   ```bash
   source setup.sh --down
   ```

2. Set a larger VLM model (e.g., upgrade from 3B to 7B parameters):

   ```bash
   export VLM_MODEL_NAME="Qwen/Qwen2.5-VL-7B-Instruct"
   ```

3. Restart the application:

   ```bash
   source setup.sh --summary
   ```

**Alternative Models to Try**:

- For CPU: `Qwen/Qwen2.5-VL-7B-Instruct` (larger version)
- For GPU: Consider other supported VLM models with higher parameter counts

> **Note:** Larger models will require more system resources (RAM or VRAM) and may have longer inference times, but typically provide more accurate and coherent summaries.