# How to Enable Debug Logging in docker-icloudpd for Troubleshooting

> Troubleshoot docker-icloudpd issues by enabling debug logging. Learn how to set debug logging true in icloudpd conf or use the enable debugging flag for detailed insights.

- Repository: [boredazfcuk/docker-icloudpd](https://github.com/boredazfcuk/docker-icloudpd)
- Tags: how-to-guide
- Published: 2026-02-26

---

**Set `debug_logging=true` in [`/config/icloudpd.conf`](https://github.com/boredazfcuk/docker-icloudpd/blob/main//config/icloudpd.conf) or run the container with `--enable-debugging` to activate detailed debug output that reveals user IDs, cookie paths, and API request URLs.**

When troubleshooting authentication failures or sync issues with `docker-icloudpd`, enabling debug logging provides the granular visibility needed to diagnose problems. This containerized iCloud Photos downloader uses a simple boolean flag to toggle between standard info-level output and verbose debug traces that expose internal state and network operations.

## Understanding the Debug Logging Configuration

The debug logging system centers on a single configuration variable read from the container's environment file.

### Configuration File Location

The setting lives in [`/config/icloudpd.conf`](https://github.com/boredazfcuk/docker-icloudpd/blob/main//config/icloudpd.conf), which persists across container restarts when mounted as a volume. During initialization, the container generates this file with default values if it does not exist.

### Default Settings in init_config.sh

In [`init_config.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/init_config.sh) (lines 86-87), the `debug_logging` variable defaults to `false`:

```bash
debug_logging="${debug_logging:=false}"

```

This ensures that fresh installations operate with standard logging verbosity unless explicitly configured otherwise.

## Three Methods to Enable Debug Logging

You can activate debug output through manual configuration, helper commands, or temporary runtime flags.

### Method 1: Edit the Configuration File Manually

Append the setting directly to the configuration file:

```bash
echo "debug_logging=true" >> /config/icloudpd.conf

```

Alternatively, open [`/config/icloudpd.conf`](https://github.com/boredazfcuk/docker-icloudpd/blob/main//config/icloudpd.conf) in a text editor and ensure the line reads:

```ini
debug_logging=true

```

Restart the container to apply the change. The next sync operation will emit debug-level messages.

### Method 2: Use the Built-in Helper Function

The container provides automated helpers that modify the configuration file for you. In [`sync-icloud.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/sync-icloud.sh) (lines 18-22), the `enable_debug_logging()` function rewrites the config line and logs confirmation:

```bash
enable_debug_logging(){
   sed -i 's/debug_logging=.*/debug_logging=true/' /config/icloudpd.conf
   echo "$(date '+%Y-%m-%d %H:%M:%S') INFO     Debug logging enabled"
}

```

Invoke this helper by passing `--enable-debugging` to the container entrypoint:

```bash
docker run --rm \
    -v $(pwd)/config:/config \
    boredazfcuk/docker-icloudpd \
    --enable-debugging

```

### Method 3: Temporarily Enable for a Single Run

For one-off troubleshooting without persisting the change, combine the enable flag with an immediate sync command. Note that the configuration change persists in the file, but you can manually reset it afterward or use `--disable-debugging` in a subsequent run.

## What Happens When Debug Logging Is Active

When `debug_logging` is set to `true`, the runtime behavior changes in [`sync-icloud.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/sync-icloud.sh) (lines 30-37). The script sets the `log_level` variable to `debug` and calls `log_debug` functions that print messages prefixed with `DEBUG`.

Active debug logging reveals:

- **User and group IDs** (lines 30-47 in [`sync-icloud.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/sync-icloud.sh))
- **Cookie storage paths** and authentication tokens
- **API request URLs** and HTTP headers sent to Apple's servers
- **File operation details** including path transformations and download decisions

The [`launcher.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/launcher.sh) script (line 25) also checks this flag early in the startup sequence to ensure debug mode is active before the main sync logic executes.

## How to Disable Debug Logging

To return to standard logging verbosity, use the complementary helper function defined in [`sync-icloud.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/sync-icloud.sh) (lines 24-28):

```bash
disable_debug_logging(){
   sed -i 's/debug_logging=.*/debug_logging=false/' /config/icloudpd.conf
   echo "$(date '+%Y-%m-%d %H:%M:%S') INFO     Debug logging disabled"
}

```

Execute this by running the container with `--disable-debugging`:

```bash
docker run --rm \
    -v $(pwd)/config:/config \
    boredazfcuk/docker-icloudpd \
    --disable-debugging

```

Alternatively, manually edit [`/config/icloudpd.conf`](https://github.com/boredazfcuk/docker-icloudpd/blob/main//config/icloudpd.conf) to set `debug_logging=false` and restart the container.

## Summary

- **Debug logging** in docker-icloudpd is controlled by the `debug_logging` boolean in [`/config/icloudpd.conf`](https://github.com/boredazfcuk/docker-icloudpd/blob/main//config/icloudpd.conf).
- The default value is `false`, defined in [`init_config.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/init_config.sh) (lines 86-87).
- **Enable debug mode** by editing the config file, running `--enable-debugging`, or using the `enable_debug_logging()` helper in [`sync-icloud.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/sync-icloud.sh).
- **Disable debug mode** with `--disable-debugging` or the `disable_debug_logging()` helper.
- When active, debug logging reveals user IDs, cookie paths, API URLs, and file operations via `log_debug` calls in [`sync-icloud.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/sync-icloud.sh) (lines 30-47).

## Frequently Asked Questions

### Where is the debug logging setting stored?

The setting is stored in the container's configuration file at [`/config/icloudpd.conf`](https://github.com/boredazfcuk/docker-icloudpd/blob/main//config/icloudpd.conf) as the variable `debug_logging`. This file persists across container restarts when mounted as a volume, ensuring your logging preference remains active until explicitly changed.

### Can I enable debug logging without restarting the container?

No, you must restart the container after modifying [`/config/icloudpd.conf`](https://github.com/boredazfcuk/docker-icloudpd/blob/main//config/icloudpd.conf) or using the `--enable-debugging` helper. The [`launcher.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/launcher.sh) script checks the `debug_logging` value at startup (line 25), and the [`sync-icloud.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/sync-icloud.sh) script sets the log level during initialization (lines 30-37), so changes require a restart to take effect.

### What information does debug logging reveal?

Debug logging exposes internal operational details including user and group IDs, cookie storage paths, authentication tokens, API request URLs sent to Apple's servers, HTTP headers, and granular file operation details such as path transformations and download decisions. These details appear as `DEBUG` prefixed messages via the `log_debug` function in [`sync-icloud.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/sync-icloud.sh).

### Is debug logging persistent across container restarts?

Yes, when you enable debug logging using either the `--enable-debugging` flag or by manually editing [`/config/icloudpd.conf`](https://github.com/boredazfcuk/docker-icloudpd/blob/main//config/icloudpd.conf), the change persists across restarts because the configuration file is stored in a mounted volume. The setting remains active until you explicitly disable it using `--disable-debugging` or by setting `debug_logging=false` in the configuration file.