Debugging Guide¶

Potato has several command-line flags and config options for debugging and testing an annotation project.

Server Configuration¶

You can configure server settings directly in your YAML config file instead of using CLI flags:

server:
  port: 8000        # Port to run on (default: 8000)
  host: "0.0.0.0"   # Host to bind to (default: 0.0.0.0)
  debug: false      # Enable Flask debug mode (default: false)

Note: CLI flags take precedence over config file values. For example, -p 9000 will override server.port: 8000.

Debug Flags¶

`--debug`¶

Launches Potato in debug mode with simplified authentication.

potato start config.yaml --debug

Effects: - Bypasses normal login requirements - Enables verbose logging - Useful for quickly testing configuration changes

`--debug-log`¶

Controls debug logging output for different parts of the system.

potato start config.yaml --debug --debug-log=all

Options:

Value	Description
`all`	Enable logging for both UI (frontend) and server (backend)
`ui`	Enable frontend JavaScript console logging only
`server`	Enable backend Python logging only
`none`	Disable all debug logging

Examples:

# Debug frontend issues (JavaScript errors, UI state)
potato start config.yaml --debug --debug-log=ui

# Debug backend issues (API calls, data processing)
potato start config.yaml --debug --debug-log=server

# Full debugging (both frontend and backend)
potato start config.yaml --debug --debug-log=all

# Quiet mode - minimal output
potato start config.yaml --debug --debug-log=none

How it works: - When ui logging is disabled, frontend console.log, console.debug, and console.info calls are suppressed - When server logging is disabled, backend log messages below WARNING level are suppressed - You can re-enable UI logging at runtime by calling enableUIDebug() in the browser console

`--debug-phase`¶

Skip directly to a specific phase or page without going through earlier phases. This is useful for testing specific parts of an annotation workflow.

potato start config.yaml --debug --debug-phase=annotation

Requires: The --debug flag must also be set.

Valid phase names: - login - Login page - consent - Consent form - prestudy - Pre-study survey - instructions - Instructions page - training - Training phase - annotation - Main annotation phase - poststudy - Post-study survey - done - Completion page

You can also specify a specific page name if your configuration defines multiple pages within a phase.

Examples:

# Jump directly to annotation (most common use case)
potato start config.yaml --debug --debug-phase=annotation

# Test post-study survey
potato start config.yaml --debug --debug-phase=poststudy

# Test a specific named page
potato start config.yaml --debug --debug-phase=my_custom_survey

How it works: - Automatically creates and logs in a user named debug_user - Skips all phases before the specified phase - The user's state is set as if they had completed all prior phases

Combining Debug Flags¶

Flags can be combined for different debugging scenarios:

# Quick annotation testing with minimal noise
potato start config.yaml --debug --debug-phase=annotation --debug-log=none

# Full debugging of annotation phase
potato start config.yaml --debug --debug-phase=annotation --debug-log=all

# Debug only backend while testing post-study
potato start config.yaml --debug --debug-phase=poststudy --debug-log=server

Other Useful Flags¶

`--verbose` / `-v`¶

Enable verbose output for general operation logging.

potato start config.yaml -v

`--veryVerbose`¶

Enable very verbose output with detailed internal state information.

potato start config.yaml --veryVerbose

`--port` / `-p`¶

Run on a specific port (useful when running multiple instances).

potato start config.yaml -p 8080

Browser Developer Tools¶

In addition to command-line flags, you can use browser developer tools for debugging:

Console: View JavaScript logs and errors (F12 or Cmd+Option+I)
Network: Monitor API calls between frontend and backend
Elements: Inspect the DOM and CSS styling
Application: Check session storage and cookies

Re-enabling Console Logging¶

If UI logging was disabled via --debug-log=server or --debug-log=none, you can re-enable it in the browser console:

enableUIDebug();

This restores console.log, console.debug, console.info, and console.warn to their original behavior.

Common Debugging Scenarios¶

Testing a New Annotation Schema¶

# Skip to annotation with full logging
potato start config.yaml --debug --debug-phase=annotation --debug-log=all

Debugging API Issues¶

# Server-only logging to focus on backend
potato start config.yaml --debug --debug-log=server

Then use browser Network tab to inspect request/response data.

Testing User Flow¶

# Start from the beginning with UI logging
potato start config.yaml --debug --debug-log=ui

Performance Testing¶

# Minimal logging overhead
potato start config.yaml --debug --debug-phase=annotation --debug-log=none

Troubleshooting¶

"debug-phase requires --debug flag"¶

The --debug-phase option only works when --debug is also specified:

# Wrong
potato start config.yaml --debug-phase=annotation

# Correct
potato start config.yaml --debug --debug-phase=annotation

Phase not found¶

If the specified phase doesn't exist in your configuration, check: - The phase name is spelled correctly - The phase is defined in your YAML config - For custom pages, use the exact page name from your config