Troubleshooting

Database

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

$ mayan-edms.py 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]))

References:

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

References:

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

Set MAYAN_DATABASE_CONN_MAX_AGE to 0

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.

References:

Docker

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:

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

References: - https://stackoverflow.com/questions/41330514/docker-rabbitmq-persistency

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

References:

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:

volumes:
# $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.

References:

LDAP

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 ldap.py for your settings module, use something like ldaplogin.py.

References: - https://gitlab.com/mayan-edms/mayan-edms/issues/743

Passwords

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/mayan-edms.py 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/mayan-edms.py 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/mayan-edms.py 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/mayan-edms.py 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/mayan-edms.py 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/mayan-edms.py createsuperuser

Python

How to upgrade an existing Python 2 virtualenv

Use:

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

Watchfolders

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.

Dependencies

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.

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:

$ mayan-edms.py 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 base distributions, modify the locale file /etc/default/locale:

LANG=”en_US.UTF-8” LC_ALL=”en_US.UTF-8”

Other