Debugging Guide

Potato provides several command-line flags and configuration options to help with debugging and testing annotation projects. These are useful during development and troubleshooting.

Server Configuration

You can configure server settings directly in your YAML config file:

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 for testing a configuration on your own machine.

potato start config.yaml --debug

Effects:

• Enables verbose logging
• Turns off the session idle timeout
• Opens the admin pages without a key, for requests from this machine
• Allows --debug-phase, which signs every visitor in as debug_user

--debug on its own keeps the login page, and --debug-phase (below) skips it.

Debug mode starts on any address, the default 0.0.0.0 included, so other machines can reach the server, and you open http://localhost:<port> on your own. Two things stay with this machine. The admin pages and admin API open without a key only for requests from it, not from another machine and not through a proxy, and elsewhere they need the admin API key as usual. Werkzeug's interactive debugger, a Python console on every error page, is served only when the server is bound to 127.0.0.1. Debug phases apply to anyone who can connect, because with --debug-phase every visitor is signed in as the same debug_user, so keep debug off any server strangers can reach. Potato 2.8.2 through 2.11.0 refuse to start in debug mode on the default 0.0.0.0 address, so on those versions add --host 127.0.0.1.

--debug-log

Controls debug logging output for different parts of the system.

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

Options:

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

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

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:

• Signs every visitor in as one shared 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, use browser developer tools for debugging:

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

Re-enabling Console Logging

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

enableUIDebug();

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

Further Reading

• Preview CLI - Validate configs without running the server
• User Simulator - Automated testing with simulated users
• Local Development - Development setup

For implementation details, see the source documentation.