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

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

# 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:

# 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 (lines 61-69) toggles the global log level without using command-line flags:

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, 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 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, the Run function receives a debugLevel string argument and forwards it to RunWithOptionsAsync using the WithLogLevel(debugLevel) option (defined in 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, src/croc/croc.go, and 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, sets the global log level to debug, enabling verbose output for all internal library calls without requiring command-line flag parsing.

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