Troubleshooting and Contributing

Home · Previous: Architecture and Security

Troubleshooting

Symptom	Meaning	Next step
Admin API returns 401	Missing or incorrect bearer token	Use the token from the active data directory or your configured WLAB_ADMIN_TOKEN; unlock again after reloading
Inbox returns 404	Incorrect private inbox token	Copy the current URL from the unlocked workbench
Capture returns 413	Body exceeds 256 KiB	Reproduce with a smaller synthetic payload
Capture returns 507	The 5,000-event cap was reached	Stop capture; use a separate WLAB_DATA_DIR for a new session and preserve the old directory
Replay returns 422	Invalid request or unknown target	Check the JSON body and target names in /api/config
Attempt fails with connection error	Receiver cannot be reached	Start the receiver and check the configured host and port
Attempt fails on redirect	Redirects are intentionally not followed	Configure the destination endpoint directly
Replay API returns 200 but delivery failed	API success and destination success differ	Inspect attempt status and status_code
Attempt is interrupted	Delivery outcome was not finalized	Inspect receiver state before retrying; side effects may already have occurred
New event is missing from the UI	Refresh is manual; results are paginated	Refresh, inspect pagination, and clear the loaded-page filter

Changing WLAB_DATA_DIR creates an independent session and token. Existing data is not migrated automatically. There is no deletion/retention UI yet.

Startup problems

• Run from the repository root using Python 3.12+ and the environment where you installed dependencies.
• If PowerShell blocks activation, run .\.venv\Scripts\python.exe directly.
• If port 8000 is occupied, choose another WLAB_PORT before startup and open that port in the browser.
• For invalid WLAB_TARGETS, use a JSON object of nonempty names and HTTP(S) URLs. Names cannot start with demo-; URLs cannot contain credentials, queries or fragments.
• Run only one app process. In containers, loopback points to the container itself.

Where to participate

You want to…	Best place
Share your first-run experience	503 → 200 challenge
Discuss duplicates and crash recovery	Idempotency discussion
Suggest what should ship next	Feature discussion
Report a reproducible bug	Issues
Propose code or documentation	Contribution guide

English and Spanish are welcome. No hace falta tener la solución: un caso reproducible o una explicación de lo que te confundió ya ayuda.

A useful bug report

Include OS, Python version, commit/version, minimal reproduction steps, expected behavior, actual behavior and a synthetic payload. Remove tokens, private inbox URLs and personal data. For a suspected vulnerability, follow the security policy instead of posting sensitive details publicly.

Validate a contribution

From the activated virtual environment:

python -m pip install -r requirements-dev.lock
python -m pytest -q
python -m ruff check .
python -m ruff format --check .

On Windows without activation, substitute .\.venv\Scripts\python.exe for python. Add tests for changed behavior rather than unrelated scope.

The Checks workflow runs on Windows and Linux. Docker runtime validation and external first-run feedback remain useful contributions.

Looking for a starting point? Try one guide from this Wiki and describe one improvement with a concrete example in Discussions.