Skip to content

Troubleshooting Guide

This guide helps you resolve common issues with Immich Stack.

Common Issues

API Connection Issues

Symptoms:

  • "Failed to connect to Immich API"
  • "API request failed"
  • "Invalid API key"

Solutions:

  1. Verify API URL is correct
    API_URL=http://immich-server:2283/api
    
  2. Check API key validity
    API_KEY=your_valid_api_key
    
  3. Ensure network connectivity
    curl -I http://immich-server:2283/api
    

Stack Creation Issues

Symptoms:

  • "Failed to create stack"
  • "Invalid stack data"
  • "Stack already exists"

Solutions:

  1. Enable dry run mode to test
    DRY_RUN=true
    
  2. Check stack criteria
    CRITERIA='[{"key":"originalFileName","split":{"delimiters":["~","."],"index":0}}]'
    
  3. Verify asset data
    WITH_ARCHIVED=true
    WITH_DELETED=false
    

Grouping Issues

Symptoms:

  • "Invalid grouping criteria"
  • "No assets grouped"
  • "Unexpected grouping results"

Solutions:

  1. Review criteria configuration
    CRITERIA='[{"key":"localDateTime","delta":{"milliseconds":1000}}]'
    
  2. Check parent selection
    PARENT_FILENAME_PROMOTE=edit,raw
    PARENT_EXT_PROMOTE=.jpg,.dng
    
  3. Enable debug logging
    LOG_LEVEL=debug
    

Burst Photo Ordering Issues

Symptoms:

  • Burst photos not ordered correctly (e.g., 0000, 0002, 0003, 0001 instead of 0000, 0001, 0002, 0003)
  • Numeric promote strings matching in wrong places (e.g., "0001" matching in timestamps)
  • Need to handle sequences with varying number of digits (1, 10, 100)

Solutions:

  1. Use the sequence keyword for flexible sequence handling (Recommended)
# Order any numeric sequence regardless of digits
PARENT_FILENAME_PROMOTE=sequence

# Prioritize COVER files, then order by sequence
PARENT_FILENAME_PROMOTE=COVER,sequence

# Only match 4-digit sequences (0001, 0002, etc.)
PARENT_FILENAME_PROMOTE=sequence:4

# Only match sequences with specific prefix
PARENT_FILENAME_PROMOTE=sequence:IMG_
  1. Use comma-separated numeric sequences for burst photos (Legacy)
PARENT_FILENAME_PROMOTE=0000,0001,0002,0003

The system will automatically detect this as a sequence and order photos correctly.

  1. The sequence detection works with various patterns:
# Pure numbers
PARENT_FILENAME_PROMOTE=0000,0001,0002,0003

# Prefixed numbers
PARENT_FILENAME_PROMOTE=IMG_0001,IMG_0002,IMG_0003

# Suffixed numbers
PARENT_FILENAME_PROMOTE=1a,2a,3a
  1. Files with numbers beyond your promote list are handled automatically:

  2. If you specify 0000,0001,0002,0003 but have files up to 0999, they will be sorted correctly at position 999

  3. Understanding sequence:X behavior:

  4. sequence - Matches any numeric sequence (1, 2, 10, 100, etc.)
  5. sequence:4 - Matches ONLY 4-digit numbers (0001, 0002, not 1, 10, 100)
  6. sequence:IMG_ - Matches only files with IMG_ prefix followed by numbers

Cron Mode Issues

Symptoms:

  • "Cron job not running"
  • "Invalid interval"
  • "Unexpected execution"

Solutions:

  1. Verify run mode
    RUN_MODE=cron
    
  2. Check interval setting
    CRON_INTERVAL=3600
    
  3. Monitor logs
    LOG_LEVEL=debug
    LOG_FORMAT=json
    

Debugging

Enable Debug Logging

LOG_LEVEL=debug
LOG_FORMAT=json

Check Logs

# View logs
docker logs immich-stack

# Follow logs
docker logs -f immich-stack

Test Configuration

  1. Use dry run mode
DRY_RUN=true
  1. Test with minimal criteria
CRITERIA='[{"key":"originalFileName"}]'
  1. Verify API connection
    curl -I $API_URL
    

Performance Issues

High Memory Usage

Solutions:

  1. Process fewer assets at once
  2. Use more specific criteria
  3. Enable pagination

Slow Processing

Solutions:

  1. Optimize criteria
  2. Use appropriate delta values
  3. Consider batch processing

Best Practices

  1. Testing

  2. Always use dry run mode first

  3. Test with small asset sets
  4. Verify criteria before production

  5. Monitoring

  6. Enable debug logging

  7. Monitor resource usage
  8. Check operation results

  9. Maintenance

  10. Regular stack cleanup

  11. API key rotation
  12. Configuration review

  13. Security

  14. Secure API keys
  15. Regular updates
  16. Access control