# How to Debug Superfile Issues Using Debug Mode Configuration

> Easily debug Superfile issues by enabling debug mode. Learn to use the configuration file or CLI flag for system diagnostics and dependency info. Resolve problems faster.

- Repository: [Yorukot/superfile](https://github.com/yorukot/superfile)
- Tags: how-to-guide
- Published: 2026-07-30

---

**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)](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:

```toml

# 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)](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)](https://github.com/yorukot/superfile/blob/main/src/cmd/main.go#L84-L89):

```bash
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)](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:

```bash
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`](https://github.com/yorukot/superfile/blob/main/src/internal/ui/filepanel/update.go)
- **Zoxide navigation queries** logged in [`src/internal/ui/zoxide/model.go`](https://github.com/yorukot/superfile/blob/main/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:

```bash
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`](https://github.com/yorukot/superfile/blob/main/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:

```bash
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)](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)](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)](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)](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)](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`](https://github.com/yorukot/superfile/blob/main/src/internal/config_function.go) only checks this value at startup, so a restart is required to change verbosity levels.