Troubleshooting Guide¶

Common Issues and Solutions¶

Backend Issues¶

Issue: 500 Error on Shipments Board¶

Symptoms:

ValueError: 'PACKAGED' is not a valid ShipmentStatus

Cause: Database has invalid status value.

Solution:

UPDATE shipment SET status = 'PACKED' WHERE status = 'PACKAGED';

Prevention: See PROBLEM-001 in saas-backend/problems/

Issue: Missing DB Columns¶

Symptoms:

sqlalchemy.exc.ProgrammingError: column shipment.recipient_id does not exist

Cause: Migration not applied or model changed without migration.

Solution:

# Check current migration state
uv run alembic current

# Apply pending migrations
uv run alembic upgrade head

# If still missing, manually add column
ALTER TABLE shipment ADD COLUMN recipient_id UUID;

Prevention: Always run alembic upgrade head after model changes. See PROBLEM-002.

Issue: StatusHistoryModel.metadata AttributeError¶

Symptoms:

AttributeError: 'StatusHistoryModel' object has no attribute 'metadata'

Cause: Using metadata as field name conflicts with SQLAlchemy reserved attribute.

Solution: Rename field to event_metadata with sa_column=Column("metadata", ...).

See PROBLEM-004 in saas-backend/problems/

Frontend Issues¶

Issue: Scanner Button Not Opening Camera¶

Symptoms: Camera doesn't open on mobile.

Possible causes: 1. flet-camera package not installed 2. Platform doesn't support camera (web/desktop) 3. Permission not granted

Solution: 1. Verify package: uv pip show flet-camera 2. Check platform: only works on iOS/Android 3. Grant camera permission when prompted

Issue: App Not Responding After Language Change¶

Symptoms: UI doesn't update after changing language.

Cause: refresh_and_update() not called after set_language().

Solution:

async def change_language(page, lang_code):
    await set_language(Lang(lang_code))
    await refresh_and_update(page)  # This is required

Getting Help¶

Check PROBLEMS.md in project root for documented issues
Check CHANGELOG.md for recent changes
Run tests: uv run pytest tests/ -v
Check logs in Docker: docker-compose logs -f

Reporting Issues¶

When reporting a new issue: 1. Document steps to reproduce 2. Include error message and stack trace 3. Note environment (OS, Python version) 4. Check if similar issue exists in PROBLEMS.md