# How to Debug croc Issues with the --debug Flag and Logs

> Debug croc issues effectively using the --debug flag to reveal detailed diagnostic messages during connection handshakes, encryption, and packet transfers. Troubleshoot faster with enhanced logging.

- Repository: [Zack/croc](https://github.com/schollz/croc)
- Tags: how-to-guide
- Published: 2026-07-26

---

**Enable the `--debug` flag when running croc to switch the global log level from info to debug, outputting detailed diagnostic messages—including connection handshakes, encryption steps, and packet statistics—to stdout for troubleshooting.**

When troubleshooting file transfer failures or connection timeouts in [croc](https://github.com/schollz/croc), verbose diagnostic logging is essential for pinpointing the root cause. The `--debug` flag activates a comprehensive trace of internal operations, from TCP connection establishment to encryption key exchange. This guide explains how to enable and capture these logs, along with the underlying implementation details from the `schollz/croc` source code.

## Enabling Debug Mode from the Command Line

The `--debug` flag is defined in [`src/cli/cli.go`](https://github.com/schollz/croc/blob/main/src/cli/cli.go) at line 134 and processed during argument parsing between lines 255-257. When detected, the CLI immediately sets the global log level to debug using `log.SetLevel("debug")` and emits a confirmation message (`log.Debug("debug mode on")`).

To view detailed logs during a file transfer, append the flag to either the send or receive command:

```bash

# Send a file with debug output enabled

croc send --debug myfile.txt

# Receive a file with debug output enabled

croc recv --debug

```

## Understanding croc Debug Log Output

When debug mode is active, croc prints granular diagnostic information to stdout that includes:

- **Connection events** – TCP establishment and teardown sequences
- **Encryption details** – Key exchange steps without exposing secret material
- **Packet statistics** – Send/receive counts, acknowledgments, and retransmission attempts
- **Error context** – Warnings and errors wrapped with detailed state information

This output allows you to trace exactly where a transfer fails, whether during the initial relay connection, the PAKE encryption handshake, or the actual data transmission phase.

## Capturing croc Debug Logs to a File

Because debug logs write to stdout, you can redirect them to a file for offline analysis or sharing with support teams:

```bash

# Save debug logs while sending a file

croc send --debug myfile.txt > send_debug.log 2>&1

# Save debug logs while receiving

croc recv --debug > recv_debug.log 2>&1

```

Redirecting both stdout and stderr ensures you capture all diagnostic messages, including any runtime errors or warning-level logs.

## Enabling Debug Mode Programmatically

For Go developers integrating croc as a library, the `Debug(bool)` helper function in [`src/croc/croc.go`](https://github.com/schollz/croc/blob/main/src/croc/croc.go) (lines 61-69) toggles the global log level without using command-line flags:

```go
import "github.com/schollz/croc/src/croc"

func main() {
    // Enable verbose logging for internal library calls
    croc.Debug(true)
    
    // Continue with your transfer logic...
}

```

Calling `croc.Debug(true)` executes `log.SetLevel("debug")`, mirroring the behavior of the CLI flag for programmatic use cases.

## Technical Implementation of croc's Debug System

The debug flag propagates through several layers of the codebase:

**Flag Definition and Parsing**  
In [`src/cli/cli.go`](https://github.com/schollz/croc/blob/main/src/cli/cli.go), the boolean flag is registered at line 134. The parsing logic at lines 255-257 checks `c.Bool("debug")` and immediately adjusts the log level before any transfer begins.

**Default Log Levels**  
The constant `DEFAULT_LOG_LEVEL` is defined as `"debug"` in [`src/tcp/defaults.go`](https://github.com/schollz/croc/blob/main/src/tcp/defaults.go) at line 6. However, the CLI overrides this to `"info"` by default, ensuring verbose output only appears when explicitly requested.

**TCP Layer Application**  
In [`src/tcp/tcp.go`](https://github.com/schollz/croc/blob/main/src/tcp/tcp.go), the `Run` function receives a `debugLevel` string argument and forwards it to `RunWithOptionsAsync` using the `WithLogLevel(debugLevel)` option (defined in [`src/tcp/options.go`](https://github.com/schollz/croc/blob/main/src/tcp/options.go)). Inside the server initialization, line 92 applies the level via `log.SetLevel(s.debugLevel)`, ensuring all TCP connection logs respect the user's preference.

## Summary

- Use `--debug` with any croc command to enable verbose diagnostic output
- Debug logs print to stdout and can be redirected to files using standard shell operators
- The default log level is "info" unless overridden by the flag or programmatic API
- Internal implementation spans [`src/cli/cli.go`](https://github.com/schollz/croc/blob/main/src/cli/cli.go), [`src/croc/croc.go`](https://github.com/schollz/croc/blob/main/src/croc/croc.go), and [`src/tcp/tcp.go`](https://github.com/schollz/croc/blob/main/src/tcp/tcp.go)
- The `croc.Debug(bool)` function allows library consumers to toggle logging without CLI flags

## Frequently Asked Questions

### How do I enable debug logging when sending a file with croc?

Append the `--debug` flag to your send command: `croc send --debug filename`. This immediately switches the global log level from info to debug and prints detailed connection and encryption diagnostics to your terminal.

### Where does croc output debug logs by default?

croc writes all debug logs to **stdout**. You can capture them to a file using redirection operators like `> debug.log 2>&1` to preserve both standard output and error streams for later analysis.

### What information is included in croc's debug logs?

The logs contain TCP connection establishment events, encryption key exchange progress (without exposing secrets), packet transmission statistics, retransmission attempts, and detailed error context. This granularity helps identify whether failures occur during networking, cryptography, or file I/O operations.

### Can I enable debugging programmatically in my own Go application using croc?

Yes. Import `github.com/schollz/croc/src/croc` and call `croc.Debug(true)` before initiating transfers. This function, located at lines 61-69 in [`src/croc/croc.go`](https://github.com/schollz/croc/blob/main/src/croc/croc.go), sets the global log level to debug, enabling verbose output for all internal library calls without requiring command-line flag parsing.