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

Infinite Re-stacking Loop (Issue #35)¶

Fixed in: Commit 2c3a75a (November 1, 2025)

Symptoms:

Same assets processed repeatedly across runs
Different queue positions for same asset IDs (e.g., 338/4275, then 772/4278)
False "Success! Stack created" messages for stacks that already exist
Cron mode infinite loop on same subset of photos
No progress through entire photo library
Stack count remains static across runs

Root Cause:

The stacksMap only indexed PRIMARY assets of each stack, not all child assets. When checking if an asset was already stacked, child assets were not found, causing the tool to repeatedly attempt to restack them.

Resolution:

The fix changed stack indexing from:

// Old: Only indexed primary asset
stacksMap[stack.PrimaryAssetID] = stack

To:

// New: Index ALL assets in the stack
for _, asset := range stack.Assets {
    stacksMap[asset.ID] = stack
}

Verification:

If you experienced this issue, update to the latest version and verify:

Check logs no longer show same asset IDs repeatedly
Stack count should increase steadily across runs
Queue positions should progress sequentially
"Success! Stack created" should only appear for genuinely new stacks

Affected Users:

Large libraries (50k+ assets)
Google Pixel camera files (RAW-01.COVER.jpg / RAW-02.ORIGINAL.dng patterns)
Users running in cron mode with frequent intervals

Related:

GitHub Issue: #35
Commit: 2c3a75a

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

Stack Recovery Procedures¶

When to Use:

After failed stack operations
When migrating between criteria
After database issues
When cleaning up corrupted stacks

Complete Stack Reset:

# CAUTION: This will delete ALL existing stacks
RUN_MODE=once
RESET_STACKS=true
CONFIRM_RESET_STACK="I acknowledge all my current stacks will be deleted and new one will be created"

# Run the stacker
./immich-stack

Important Notes:

RESET_STACKS only works with RUN_MODE=once
Using RESET_STACKS in cron mode results in an error
Confirmation text must match exactly
Always test with DRY_RUN=true first

Recovering from Partial Failures:

Enable replace stacks mode to fix existing stacks:

REPLACE_STACKS=true
DRY_RUN=false

Remove single-asset stacks (cleanup):

REMOVE_SINGLE_ASSET_STACKS=true

Process incrementally with filters:

WITH_ARCHIVED=false
WITH_DELETED=false

Safe Recovery Workflow:

First, run in dry-run mode to preview changes:

DRY_RUN=true
REPLACE_STACKS=true
LOG_LEVEL=debug

Review the logs carefully to verify expected behavior
Execute the actual operation:

DRY_RUN=false
REPLACE_STACKS=true

Monitor logs for errors:
```
docker logs -f immich-stack
```

Rolling Back Changes:

If you need to revert to a previous state:

Use Immich database backups (if available)
Run complete reset with previous criteria configuration
Manually adjust stacks via Immich UI for specific cases

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