How to Debug Superfile Issues Using Debug Mode Configuration

Enable debug mode in Superfile by setting debug = true in the configuration file or use the spf --debug-info CLI flag to print system diagnostics and dependency information.

The yorukot/superfile repository provides built-in debugging facilities that help you diagnose crashes, preview failures, and navigation issues. These tools rely on a combination of configuration flags and command-line options that control the internal slog logger verbosity and expose runtime environment details.

Enabling Debug Mode in Superfile

Superfile offers two primary methods for activating diagnostic output: persistent configuration changes and one-off CLI commands.

Configuration File Method

The persistent debug setting is controlled by the debug boolean in the TOML configuration. According to the source analysis, this field is defined at lines 76-78 in [src/superfile_config/config.toml](https://github.com/yorukot/superfile/blob/main/src/superfile_config/config.toml#L76-L78) and maps to common.Config.Debug in the application.

To enable verbose logging:

1. Open your user configuration file (default: ~/.config/superfile/config.toml).
2. Set the debug flag to true:

# Enable verbose logging

debug = true

3. Save the file and restart Superfile.

When debug = true, the logger initialization code in [src/internal/config_function.go](https://github.com/yorukot/superfile/blob/main/src/internal/config_function.go#L44-L48) sets the level to slog.LevelDebug, causing every slog.Debug call throughout the codebase to write to the log file.

CLI Flag Method

For temporary diagnostics without modifying configuration files, use the --debug-info (or -d) flag defined in [src/cmd/main.go](https://github.com/yorukot/superfile/blob/main/src/cmd/main.go#L84-L89):

spf --debug-info

# Or use the shorthand:

spf -d

This invokes the printDebugInfo function in [src/cmd/debug_info.go](https://github.com/yorukot/superfile/blob/main/src/cmd/debug_info.go#L38-L41), which prints a formatted dump of version information, system architecture, configuration paths, and external dependency status directly to stdout.

Understanding the Debug Output

Once debug mode is active, Superfile exposes detailed runtime information through log files and terminal output.

Log File Location and Structure

The log file location varies by platform but can be discovered using the built-in path command:

spf path-list

# Look for the log file path entry

By default, logs are written to ~/.local/state/superfile/superfile.log. When debug mode is enabled, this file captures:

• UI rendering decisions from components like src/internal/ui/filepanel/update.go
• Zoxide navigation queries logged in src/internal/ui/zoxide/model.go
• Metadata extraction events when ExifTool initializes
• Runtime metrics including memory usage and object sizes

Debug Information Dump

The --debug-info output includes critical system context for bug reports:

spf --debug-info

Sample output includes:

• Version: Superfile build version (e.g., v2.5.0)
• System: OS, architecture, and kernel version
• Configuration paths: Location of config.toml and log files
• Dependencies: Status of external tools including ffmpeg, exiftool, and zoxide

Troubleshooting Common Issues

Use the following workflow to isolate and resolve problems using Superfile's debug capabilities.

Checking External Dependencies

Many Superfile features depend on external binaries. The printDebugInfo function automatically checks for:

• ffmpeg: Required for video previews
• exiftool: Required for metadata extraction
• zoxide: Required for smart directory jumping

Run spf --debug-info and examine the "Dependencies" section. Missing binaries here often explain why specific features fail silently.

Analyzing Runtime Logs

When investigating crashes or hangs:

1. Enable debug = true in your config and restart
2. Reproduce the problematic operation
3. Examine the log tail:

tail -n 50 ~/.local/state/superfile/superfile.log

Look for slog.Debug entries that indicate panel updates, file operations, or Zoxide queries immediately preceding the error.

Reproducing Issues with Debug Logging

For consistent bug reporting:

1. Clear or backup existing logs to isolate new output
2. Enable debug mode via the configuration file method
3. Perform the minimal steps needed to trigger the issue
4. Collect the log file and spf --debug-info output for your issue report

Key Source Files and Implementation Details

Understanding the implementation helps interpret debug output correctly:

File	Purpose	Key Function
[src/superfile_config/config.toml](https://github.com/yorukot/superfile/blob/main/src/superfile_config/config.toml)	Default configuration template	Defines the debug field at lines 76-78
[src/cmd/main.go](https://github.com/yorukot/superfile/blob/main/src/cmd/main.go)	CLI entry point	Defines --debug-info flag at lines 84-89
[src/internal/config_function.go](https://github.com/yorukot/superfile/blob/main/src/internal/config_function.go)	Configuration loader	Initializes logger at lines 44-48 based on common.Config.Debug
[src/cmd/debug_info.go](https://github.com/yorukot/superfile/blob/main/src/cmd/debug_info.go)	Diagnostics printer	Implements printDebugInfo at lines 38-41
[src/pkg/utils/log_utils.go](https://github.com/yorukot/superfile/blob/main/src/pkg/utils/log_utils.go)	Logging utilities	Helper functions for test log output

Summary

• Set debug = true in ~/.config/superfile/config.toml to enable persistent DEBUG-level logging to the superfile log file.
• Use spf --debug-info (or spf -d) for a one-time diagnostic dump without modifying configuration files.
• Check external dependencies (ffmpeg, exiftool, zoxide) in the debug output when troubleshooting preview or navigation failures.
• Locate logs using spf path-list and examine ~/.local/state/superfile/superfile.log for detailed runtime traces.
• Restart Superfile after changing the debug configuration to apply logger level changes.

Frequently Asked Questions

Where is the Superfile log file located?

The log file path varies by operating system. Run spf path-list to display the exact location on your system. On most Linux systems, the default is ~/.local/state/superfile/superfile.log.

How do I enable debug mode without editing the config file?

Use the --debug-info flag (shorthand -d) to print a diagnostic summary to stdout: spf --debug-info. Note that this prints information once and exits, unlike the config file method which enables continuous debug logging during normal operation.

What external dependencies does Superfile check in debug mode?

The --debug-info output validates the presence of ffmpeg (video processing), exiftool (metadata extraction), and zoxide (smart directory navigation). Missing dependencies in this list often explain why specific features like image previews or directory jumping fail to function.

How do I disable debug logging once enabled?

Open your configuration file (~/.config/superfile/config.toml by default), change debug = true to debug = false, save the file, and restart Superfile. The logger initialization in src/internal/config_function.go only checks this value at startup, so a restart is required to change verbosity levels.

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