MySQL error: OperationalError: (1267, "Illegal mix of collations (latin1_swedish_ci, IMPLICIT) and (utf8_general_ci, COERCIBLE) for operation '='”)

$ shell
>>> from django.db import connection
>>> cursor = connection.cursor()
>>> cursor.execute('SHOW TABLES')
>>> results=[]
>>> for row in cursor.fetchall(): results.append(row)
>>> for row in results: cursor.execute('ALTER TABLE %s CONVERT TO CHARACTER SET utf8 COLLATE utf8_general_ci;' % (row[0]))


MySQL error: Incorrect string value: `'xE2x80x95rs6…'` for column `'content'` at row 1

When using MySQL and doing OCR on languages other than English

Use utf-8 collation on MySQL server, or at least in table ‘documents_documentpage’, ‘content’ field


MySQL error: Error "django.db.utils.IntegrityError IntegrityError: (1452, 'Cannot add or update a child row: a foreign key constraint fails (`…`.`…`, CONSTRAINT `…_refs_id_b0252274` FOREIGN KEY (`…`) REFERENCES `…` (`…`))')

Solution: Convert all MySQL tables to the same type, either all MyISAM or InnoDB

PostgreSQL error: OperationalError: FATAL:  sorry, too many clients already


This setting keeps a database connection alive. It allows reuse of database connections. When Mayan EDMS is deployed with Gunicorn a microthreads backend, the database connections are not shared and this setting has the reverse effect of exhausting the available PostgreSQL connections available. To avoid this, Setting MAYAN_DATABASE_CONN_MAX_AGE to 0 will cause all microthreads to release their connections, by closing them when finished.


MySQL error: ValueError: Found wrong number (0) of constraints for actstream_follow(user_id, content_type_id, object_id)

This is caused by a bug in Django 1.11. The issue has been fixed for Django 2.0 version which Mayan EDMS will be migrating to for version 4.0.

Mitigation: Avoid MySQL versions: 8.0.x. Use MySQL 5.7 or earlier.

References: - - -


RabbitMQ is not being persisting messages despite using Docker Volumes

Docker will create a randomly generated hostname for each container every time you deploy a new container instance.

RabbitMQ stores persistent message/queue data using a folder structure based off a node’s hostname. If you do not set a static container hostname, then RabbitMQ will loose any unprocessed messages if you launch a new RabbitMQ container or do a docker-compose down/up.

This happens even if you use a persistent volume (docker run -v).

This will result in tasks being lost and may be the reason a document has not been OCR’d or processed completely.

Solution: Ensure you run the RabbitMQ container with the --hostname option when starting, ensuring RabbitMQ uses a static folder name every time it starts, such as:

docker run -d --name mayan-rabbitmq --hostname mayan-rabbitmq --restart=always...

For Docker Compose:

    container_name: mayan-edms-rabbitmq
    image: rabbitmq:3-management
    hostname: mayan-edms-rabbitmq
    RABBITMQ_DEFAULT_PASS: mayanrabbitpass
    - mayan-bridge
    restart: unless-stopped
    - /docker-volumes/mayan-edms/rabbitmq:/var/lib/rabbitmq

References: -

MAYAN_APT_INSTALLS does not work for Archlinux with kernels > 4.14

This is caused by a change from kernel 4.18 - 4.19. Metacopy on these kernels is set to yes in archlinux kernels (/sys/module/overlay/parameters/metacopy) and overlayfs should override this which it does not at the moment.

The workaround is to disable metacopy:

echo N | sudo tee /sys/module/overlay/parameters/metacopy


Error: IOError: [Errno 37] No locks available when using a NFS volume for MAYAN_MEDIA_ROOT

This is caused by an upstream Django issue and occurrs when using a NFS volume for MAYAN_MEDIA_ROOT. File lock issues can prevent Mayan from generating the static media inside MAYAN_MEDIA_ROOT.

If you’re using NFSv3, ensure that rcp.statd is running on the NFS client (called nfs-lock on some distributions) and that no_auth_nlm is set in /etc/exports on the NFS Server. NFSv4 has locking built in so does not require rcp.statd, but may require no_auth_nlm set on the NFS Server.

A workaround if the issue persists after applying the above is to deploy Mayan with a NFS MAYAN_MEDIA_ROOT with a local-only volume for MAYAN_MEDIA_ROOT/static. An example volume section inside docker-compose:

# $MAYAN_MEDIA_ROOT can be mounted to nfs and shared between nodes. Change /mnt/mayan-shared
# to the path of the mounted NFS export
- /mnt/mayan-shared/media:/var/lib/mayan

# $MAYAN_MEDIA_ROOT/static must be local to avoid locking issues
- /docker-volume/static:/var/lib/mayan/static

# Other mounts (such as watch folder). Must be on a different NFS export to avoid lock issues
- /mnt/watch:/srv/watch_folder

Alternatively, you can use non-NFS backed volumes for the whole MAYAN_MEDIA_ROOT share where no local static directory is required. Samba and iSCSI are known to work.



If you get a No module named 'ldap.filter' error when starting Mayan EDMS after enabling LDAP, make sure your LDAP settings module is not using the same name as a Python or Django library. Instead of using for your settings module, use something like

References: -


Admin password reset

To reset the password of the admin account use the following command:

MAYAN_MEDIA_ROOT=<your Mayan media root setting> <installation directory>/bin/ changepassword admin

If you followed the deploying instructions from the documentation your MAYAN_MEDIA_ROOT will be /opt/mayan-edms/media.

If using a Docker image, execute the command inside the container. First you need to know the name of the Docker container running Mayan EDMS on your setup with:

docker ps

Then execute the password reset command inside the Docker container:

docker exec -ti <your docker container name> /opt/mayan-edms/bin/ changepassword admin

Another way to do this is to execute a shell inside the container to get a command prompt:

docker exec -ti <your docker container name> /bin/bash

And then execute the command:

/opt/mayan-edms/bin/ changepassword admin

Missing automatic admin account after installation

This is caused when the initialsetup command is interrupted as the admin user is created outside of the database migrations.

To create an admin super user account manually use the command:

MAYAN_MEDIA_ROOT=/opt/mayan-edms/media /opt/mayan-edms/bin/ createsuperuser

If you followed the deploying instructions from the documentation your MAYAN_MEDIA_ROOT will be /opt/mayan-edms/media.

If using a Docker image, execute the command inside the container. First find you container name with:

docker ps

Then execute the command inside the container:

docker exec -ti <your docker container name> /opt/mayan-edms/bin/ createsuperuser

Another way to do this is to execute a shell inside the container to get a command prompt:

docker exec -ti <your docker container name> /bin/bash

And then execute the command:

/opt/mayan-edms/bin/ createsuperuser


How to upgrade an existing Python 2 virtualenv


virtualenv <existing directory> -p <Python 3 binary path>

If you followed the deployment instructions, the command line would be:

virtualenv /opt/mayan-edms -p /usr/bin/python3

If using a dedicated user account for Mayan EDMS:

sudo -u mayan virtualenv --clear /opt/mayan-edms -p /usr/bin/python3


Incomplete files uploaded

To avoid uploading files are they are being copied to the watchfolder, copy the files to a temporary directory on the same partition as the watchfolder first. Then move the files to the watchfolder. The move will be executed as an atomic operation and will prevent the files to be uploaded in the middle of the copying process.

The watched folder feature is not working

Make sure that the Celery BEAT scheduler is running correctly as it is the element that triggers the periodic tasks. Check that the user running the Mayan EDMS services has read and write permissions for the watch folder.


Error: unable to execute 'x86_64-linux-gnu-gcc': No such file or directory

This happens when using the MAYAN_APT_INSTALLS feature. It means that the GCC package is required to compile the packages specified with MAYAN_APT_INSTALLS.

Solution: Include gcc in the list of packages specified with MAYAN_APT_INSTALLS.


OCR is not working for my specific language

Not all Tesseract OCR language files are included to avoid increasing the size of the Docker image.

To see which languages are supported, use the command:

apt-cache search tesseract-ocr

and install the language file with (German in this example):

apt-get install tesseract-ocr-deu

If using the Docker image, pass the environment variable MAYAN_APT_INSTALLS with the corresponding Tesseract language option. Example:

-e MAYAN_APT_INSTALLS='tesseract-ocr-deu'

Static files

Mayan EDMS installed correctly and works, but static files are not served

Django’s development server doesn’t serve static files unless the DEBUG option is set to True, this mode of operation should only be used for development or testing. For production deployments the management command:

/opt/mayan-edms/bin/ preparestatic

should be used and the resulting static folder served from a webserver. For more information check the Django documentation section: howto/static-files/

Text encoding

Error: UnicodeEncodeError: 'ascii' codec can't encode characters in position ...

The operating system locale must support the Unicode character set. For Debian based distributions, modify the locale file /etc/default/locale:


User interface

Error: Missing staticfiles manifest entry for ...

Your browser is attempting to use web asserts in the cache. Clear the entire cache of your browser to force it to load the new web assets.


The system fails to start or some features are not working

Execute the checkdependencies command to verify that all the dependencies needed for a production installation are present and accessible to the system.

MAYAN_MEDIA_ROOT=<your Mayan media root setting> /<installation directory> checkdependencies

If installed using the Direct deployment method, this would be:

MAYAN_MEDIA_ROOT=/opt/mayan-edms/media /opt/mayan-edms/bin/ checkdependencies

The Docker image includes all dependencies and this process is not required.