Troubleshooting

Use this page as the first-response guide for setup, runtime, and data transfer issues.

Installation issues

Command not found (waqt or waqt-mcp)

• Confirm installer completed and shell was reloaded.
• Verify binary path is in PATH.
• For source installs, activate environment or use uv run.

Migration/database errors

uv run alembic upgrade head
uv run alembic current

Time entry issues

• Use waqt summary --date YYYY-MM-DD to verify period context.
• Use waqt edit-entry --date ... to correct bad start/end times.

Leave issues

• If no records appear, ensure date range contains weekdays.
• Duplicates may be skipped intentionally in repeated requests.

Data transfer issues

• Run import with --dry-run first.
• Set --format explicitly if extension detection is ambiguous.
• Choose --on-conflict mode based on desired behavior.

Web UI process issues

waqt ui status
waqt ui stop --force
waqt ui start --port 5555

MCP issues

• Ensure client points to the correct executable (waqt-mcp or uv run waqt-mcp).
• Check client logs and Waqt logs for protocol startup errors.

Logging and diagnostics

WAQT_LOG_LEVEL=DEBUG waqt summary
waqt --verbose start

Logs are written under the application data directory, typically in a logs/ subfolder (flask.log, cli.log, mcp.log, app.log).

Get help

• Open an issue: github.com/GMouaad/waqt/issues
• Include waqt version, OS details, exact command, and logs.