Administrator¶

FitTrackee fails to start¶

Check the database URL in environment variables if the following error is displayed in gunicorn logs:
```
sqlalchemy.exc.NoSuchModuleError: Can't load plugin: sqlalchemy.dialects:postgres
```
The variable DATABASE_URL must start with postgresql://` (engine URLs starting with ``postgres:// are no longer supported).
Check the email URL in environment variables if the following error is displayed in gunicorn logs:
```
fittrackee.emails.exceptions.InvalidEmailUrlScheme
```
A valid EMAIL_URL must be provided (see emails).

Map images are not displayed but map is shown in Workout detail¶

Check the path in environment variables. UPLOAD_FOLDER must be set with an absolute path.

Failed to upload or download files¶

Check client_max_body_size in nginx config. Increase the value to handle larger files (see nginx documentation).
Increase gunicorn timeout value if the following error is displayed in gunicorn log: [CRITICAL] WORKER TIMEOUT.

`RuntimeError: thread already started`¶

This error appears in task queue workers logs with Flask-dramatiq CLI on Python 3.13+.

The workaround is to use Dramatiq CLI directly, for instance:
```
$ dramatiq fittrackee.tasks:broker --processes=2 --log-file=dramatiq.log
```

`staticmap3.staticmap - ERROR - request failed [None]`¶

FitTrackee v0.10+ introduces a new environnement variable STATICMAP_CACHE_DIR, for Static Map 3 cache directory.

For docker installation, the directory must be writable for fittrackee user, see in docker-compose.yml example in the repository:

volumes:
  - ${UPLOAD_DIR:-./data/uploads}:/usr/src/app/uploads
  - ${LOG_DIR:-./data/logs}:/usr/src/app/logs
  - ${STATICMAP_CACHE_DIR:-./data/staticmap_cache}:/usr/src/app/.staticmap_cache
post_start:
  - command: chown -R fittrackee:fittrackee /usr/src/app/uploads /usr/src/app/logs /usr/src/app/.staticmap_cache
    user: root

`psycopg2.errors.UndefinedObject: ERROR: type "geometry" does not exist`¶

This error occurs when PostGIS extension is not installed, required with FitTrackee v1+.

To install it, see installation instructions or Upgrading to 1.x

Workouts created with a file are not displayed on the workouts map¶

If a workout has be created before FitTrackee 1.0.0, it needs to be refreshed to generate the geometry used to display the map.

See Upgrading to 1.x for instructions to recalculate all workouts with a CLI command.