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 to 0999, 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