How to Enable Debug Logging in docker-icloudpd for Troubleshooting

Set debug_logging=true in /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, 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 (lines 86-87), the debug_logging variable defaults to false:

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:

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

Alternatively, open /config/icloudpd.conf in a text editor and ensure the line reads:

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 (lines 18-22), the enable_debug_logging() function rewrites the config line and logs confirmation:

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:

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 (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)
• 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 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 (lines 24-28):

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:

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

Alternatively, manually edit /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.
• The default value is false, defined in 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.
• 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 (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 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 or using the --enable-debugging helper. The launcher.sh script checks the debug_logging value at startup (line 25), and the 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.

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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}