# How to Enable Debug Mode and Troubleshoot Issues in Superfile

> Learn to enable debug mode and troubleshoot issues in Superfile. Use the debug flag in config.toml or the --debug-info CLI for effective problem-solving and verbose logging.

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

---

**Superfile provides two primary debugging mechanisms: a persistent `debug` configuration flag in [`config.toml`](https://github.com/yorukot/superfile/blob/main/config.toml) that activates verbose `slog` logging, and a `--debug-info` CLI flag for one-off diagnostic dumps without modifying configuration files.**

When diagnosing unexpected behavior in the terminal file manager Superfile, developers and power users rely on structured logging and runtime diagnostics. According to the yorukot/superfile source code, the application exposes debugging capabilities through both a configuration toggle and command-line utilities. Understanding how to activate these features allows you to capture detailed internal state and validate system dependencies.

## Enabling Debug Mode in Superfile

Superfile supports two distinct methods for accessing diagnostic information: persistent verbose logging via the configuration file, and temporary diagnostic dumps via CLI flags.

### Configuration File Method

The primary method for sustained troubleshooting involves editing the TOML configuration file. In [`src/superfile_config/config.toml`](https://github.com/yorukot/superfile/blob/main/src/superfile_config/config.toml) (lines 76-78), the `debug` field controls the logger's verbosity level.

When `debug = true`, the initialization logic in [`src/internal/config_function.go`](https://github.com/yorukot/superfile/blob/main/src/internal/config_function.go) (lines 44-48) sets the global logger to `slog.LevelDebug`. This causes every `slog.Debug` call throughout the codebase—including UI updates, file panel operations, and zoxide queries—to be written to the log file.

To enable persistent debug mode:

1. Open your user configuration file (default: `~/.config/superfile/config.toml`, located via `spf path-list`)

2. Set the debug flag:
   ```toml
   debug = true
   ```

3. Restart Superfile to apply the changes

### Using the --debug-info CLI Flag

For immediate diagnostics without modifying configuration files, Superfile provides the `--debug-info` (or `-d`) flag defined in [`src/cmd/main.go`](https://github.com/yorukot/superfile/blob/main/src/cmd/main.go) (lines 84-89). This triggers the `printDebugInfo` function in [`src/cmd/debug_info.go`](https://github.com/yorukot/superfile/blob/main/src/cmd/debug_info.go) (lines 38-41), which outputs a formatted report containing version information, OS details, environment variables, and dependency statuses.

```bash
spf --debug-info

# or

spf -d

```

This command displays critical paths (configuration file, log file) and checks for external dependencies like `ffmpeg`, `exiftool`, and `zoxide` that affect preview and navigation functionality.

## Working with Debug Logs and System Diagnostics

Once debug mode is active, the log file becomes the primary resource for troubleshooting runtime issues.

### Locating and Reading the Log File

Superfile writes timestamped log entries to a state directory. The exact path is available through the `path-list` command:

```bash
spf path-list

```

Typically located at `~/.local/state/superfile/superfile.log`, this file contains all `slog.Debug` statements when debug mode is enabled. To monitor logs in real-time:

```bash
tail -f $(spf pl | awk '/Log file path/ {print $NF}')

```

Key debug sources to examine include:

- **UI rendering decisions** in [`src/internal/ui/filepanel/update.go`](https://github.com/yorukot/superfile/blob/main/src/internal/ui/filepanel/update.go)
- **Zoxide navigation queries** in [`src/internal/ui/zoxide/model.go`](https://github.com/yorukot/superfile/blob/main/src/internal/ui/zoxide/model.go)
- **Metadata extraction initialization** in [`src/internal/config_function.go`](https://github.com/yorukot/superfile/blob/main/src/internal/config_function.go)

### Validating External Dependencies

Many Superfile features rely on external binaries. The `--debug-info` output includes a "Dependencies" section that verifies the presence of:

- **ffmpeg**: Required for video previews
- **exiftool**: Used for metadata extraction
- **zoxide**: Powers intelligent directory jumping

If these tools are missing or not in PATH, related features will fail silently unless debug logging is enabled.

### Reproducing Issues with Verbose Logging

To effectively troubleshoot:

1. Enable `debug = true` in your configuration
2. Clear or backup the existing log file to isolate new entries
3. Restart Superfile and reproduce the problematic behavior
4. Examine the log for `slog.Debug` entries surrounding the error condition

The debug output includes internal state such as panel updates, memory statistics from `printRuntimeInfo`, and exact call stacks leading to errors.

## Summary

- **Enable persistent debugging** by setting `debug = true` in `~/.config/superfile/config.toml`, which sets the logger to `slog.LevelDebug` as implemented in [`src/internal/config_function.go`](https://github.com/yorukot/superfile/blob/main/src/internal/config_function.go)
- **Use `--debug-info`** (or `-d`) for immediate diagnostic dumps showing version, paths, and dependency statuses without configuration changes
- **Monitor `~/.local/state/superfile/superfile.log`** (path available via `spf path-list`) to view timestamped debug entries from UI components, zoxide queries, and metadata operations
- **Verify external dependencies** (ffmpeg, exiftool, zoxide) using the diagnostic output to identify missing tools causing preview or navigation failures
- **Restart Superfile** after modifying configuration to ensure the logger initializes with the correct verbosity level

## Frequently Asked Questions

### Where is the Superfile log file located?

The log file resides in your user state directory, typically `~/.local/state/superfile/superfile.log`. Run `spf path-list` (or `spf pl`) to display the exact path on your system, as this varies based on XDG environment variables and operating system conventions.

### What is the difference between the config debug flag and --debug-info?

The `debug` configuration option enables persistent verbose logging to the log file by setting the internal logger to `slog.LevelDebug`, capturing all `slog.Debug` calls continuously. In contrast, `--debug-info` is a one-time CLI command that prints a static diagnostic dump to stdout and exits immediately, without modifying the logger state or configuration files.

### Why are my debug logs not showing any verbose output?

If `debug = true` is set but you only see INFO-level messages, ensure you restarted Superfile after saving the configuration. The logger initialization occurs in [`src/internal/config_function.go`](https://github.com/yorukot/superfile/blob/main/src/internal/config_function.go) during startup, reading `common.Config.Debug` to determine the appropriate `slog` level. Without a restart, the logger retains its previous configuration.

### Does Superfile check for missing dependencies automatically?

Yes, the `printDebugInfo` function in [`src/cmd/debug_info.go`](https://github.com/yorukot/superfile/blob/main/src/cmd/debug_info.go) explicitly checks for `ffmpeg`, `exiftool`, and `zoxide` binaries in your PATH. Running `spf --debug-info` reports whether these optional dependencies are found, helping diagnose why video previews or zoxide navigation might not function as expected.