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:
- Verify API URL is correct
API_URL=http://immich-server:2283/api
- Check API key validity
API_KEY=your_valid_api_key
- 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:
- Enable dry run mode to test
DRY_RUN=true
- Check stack criteria
CRITERIA='[{"key":"originalFileName","split":{"delimiters":["~","."],"index":0}}]'
- Verify asset data
WITH_ARCHIVED=true WITH_DELETED=false
Grouping Issues¶
Symptoms:
- "Invalid grouping criteria"
- "No assets grouped"
- "Unexpected grouping results"
Solutions:
- Review criteria configuration
CRITERIA='[{"key":"localDateTime","delta":{"milliseconds":1000}}]'
- Check parent selection
PARENT_FILENAME_PROMOTE=edit,raw PARENT_EXT_PROMOTE=.jpg,.dng
- 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:
- 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_
- 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.
- 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
-
Files with numbers beyond your promote list are handled automatically:
-
If you specify
0000,0001,0002,0003
but have files up to0999
, they will be sorted correctly at position 999 -
Understanding
sequence:X
behavior: sequence
- Matches any numeric sequence (1, 2, 10, 100, etc.)sequence:4
- Matches ONLY 4-digit numbers (0001, 0002, not 1, 10, 100)sequence:IMG_
- Matches only files with IMG_ prefix followed by numbers
Cron Mode Issues¶
Symptoms:
- "Cron job not running"
- "Invalid interval"
- "Unexpected execution"
Solutions:
- Verify run mode
RUN_MODE=cron
- Check interval setting
CRON_INTERVAL=3600
- 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¶
- Use dry run mode
DRY_RUN=true
- Test with minimal criteria
CRITERIA='[{"key":"originalFileName"}]'
- Verify API connection
curl -I $API_URL
Performance Issues¶
High Memory Usage¶
Solutions:
- Process fewer assets at once
- Use more specific criteria
- Enable pagination
Slow Processing¶
Solutions:
- Optimize criteria
- Use appropriate delta values
- Consider batch processing
Best Practices¶
-
Testing
-
Always use dry run mode first
- Test with small asset sets
-
Verify criteria before production
-
Monitoring
-
Enable debug logging
- Monitor resource usage
-
Check operation results
-
Maintenance
-
Regular stack cleanup
- API key rotation
-
Configuration review
-
Security
- Secure API keys
- Regular updates
- Access control