Troubleshooting¶

Restarting PHP-FPM¶

What

PHP-FPM is a PHP extension that allows for better interaction with an application’s web server, via the use and configuration of FastCGI pools in PHP. In AtoM’s default installation configuration, Nginx will proxy PHP requests to PHP-FPM.

FastCGI is a binary protocol for interfacing interactive programs with a web server. FastCGI is a variation on the earlier Common Gateway Interface (CGI); FastCGI’s main aim is to reduce the overhead associated with interfacing the web server and CGI programs, allowing a server to handle more web page requests at once.

When

You should consider restarting PHP-FPM if:

• You have made any changes to your web server configuration
• You have made any changes to AtoM’s configuration files
• You have made any changes to the PHP pool set up during installation
• You are trying to ensure all application caches are cleared

How

sudo systemctl restart php7.4-fpm

Restarting Nginx¶

What

Nginx (pronounced “engine x”) is an open source HTTP web server (among other things). It manages the interaction between your web browser and AtoM. Your browser requests a page in AtoM, and this is sent to Nginx, which communicates with AtoM to retrieve and serve the page, or else returns an error message.

When

You should consider restarting Nginx if:

• You’ve made changes to your web server configuration

How

sudo systemctl reload nginx

Restarting memcached¶

What

Memcached is an open-source, general purpose distributed memory object caching system. It is often used to speed up dynamic database-driven websites by caching data and objects in memory to reduce the number of times an external data source (such as a database) must be read.

when

You should consider restarting Memcached if you’re using it when:

• You are trying to ensure all application caches are cleared

How

sudo systemctl restart memcached

Restarting the Job scheduler¶

What

AtoM relies on a job scheduler in order to execute certain long-running tasks asynchronously in the background (instead of synchronously via your web browser, making you wait until the task is done and the page loaded before continuing), to guarantee that web requests are handled promptly and work loads can be distributed across multiple machines. Example tasks in AtoM that use the job scheduler include:

• Generating finding aids
• Importing records via the user interface
• Exporting records via the Clipboard
• Using the Move module to reorganize archival description hierarchies
• Ingesting DIPs from Archivematica

We use Gearman as our job scheduler in AtoM. Gearman “provides a generic application framework to farm out work to other machines or processes that are better suited to do the work. It allows you to do work in parallel, to load balance processing, and to call functions between languages.”

When

You should consider restarting the atom-worker if:

• You have encountered a 500 error related to a task in AtoM supported by the job scheduler
• You have made changes to the worker configuration
• You have a job that never seems to complete in the queue

How

sudo systemctl restart atom-worker

sudo systemctl reset-failed atom-worker
sudo systemctl start atom-worker

Also, if you have multiple jobs that never seem to complete stuck in the queue, you may also want to kill the queue itself, and then restart the atom-worker. The following task will clear all jobs from the queue (including those currently running, so be careful), as well as clear the job history of previous jobs from the database. This means you will need to manually restart any jobs you would like to continue via the AtoM user interface after running this command:

php symfony jobs:clear

Other useful commands for managing the AtoM worker:

sudo systemctl enable atom-worker   # Enables the worker (on boot)
sudo systemctl start atom-worker    # Starts the worker
sudo systemctl stop atom-worker     # Stops the worker
sudo systemctl status atom-worker   # Obtains current status

For more detailed information on managing the job scheduler and the atom-worker, see:

• Asynchronous jobs and worker management

Back to top

Monitoring active processes with htop¶

Before we make any changes, it can be useful to do some basic monitoring - is this a temporary spike, or an ongoing issue? Can you reproduce the issue while monitoring resource usage and see any correlation?

If you’re familiar with the top command in Linux, this can be a useful way to quickly view all active processes. However, we find htop to be a slightly more user-friendly version of this. You can use Ubuntu’s package manager to install it:

sudo apt-get install htop

To launch htop in your terminal simply enter htop. The console will display a text-mode graph of your CPU, memory, and swap usage at the top of the page, with a detailed list of processes provided below. This should give you a better sense of whether or not you have enough resources allocated to your AtoM server. It can also be useful to try to reproduce the error(s) you are encountering while monitoring.

Back to top

Adjusting PHP execution limits¶

PHP includes several execution limits which are either configured during AtoM’s installation, or are set as defaults when PHP is installed. If you’ve encountered an error, and the web server error log includes a message like:

Fatal error: Maximum execution time of 60 seconds exceeded in ...

or:

Fatal error: Allowed memory size of 67108864 bytes exhausted (tried to allocate 233734 bytes) in ...

…then you might want to consider changing PHP’s execution limits. For more information, see:

• PHP execution limits

Remember, if you make any changes to your PHP settings (either in the php.ini file, or in your application PHP pool), you will need to restart PHP-FPM after saving your changes. See:

• Restarting PHP-FPM

Back to top

Get information about your search index¶

What

AtoM maintains an Elasticsearch search index to provide fast, full-text search results with faceting. It is this index that allows AtoM to find and display records in the user interface when browsing and searching. During the installation process, we need to configure the host, port, and index name to be used in AtoM. Once records have been added to AtoM, they are indexed by Elasticsearch to aid in discovery via the user interface.

This task will allow a system administrator to review the status of AtoM’s Elasticsearch index without having to access any configuration files. The task output will include:

• Elasticsearch version
• Search host
• Port
• Index name
• Document index status for all primary entity types in AtoM (including Accession, Actor, AIP, Function, Information object, Repository, and Term)

When

You might consider running this task if:

• Records seem to be missing from the user interface
• No records are showing in search or browse at all
• You are having trouble connecting to the search index
• You are seeking support and you suspect the issue might be search index related

Basic usage

php symfony search:status

For more information, see: Check the status of your Elasticsearch index

Populating the search index¶

What

AtoM maintains an Elasticsearch search index to provide fast, full-text search results with faceting. It is this index that allows AtoM to find and display records in the user interface when browsing and searching.

Running this task will delete the current index, then repopulate and optimize the index. Depending on the number of records in your installation, this can take a while to run - for production sites, we recommend running this task after regular business hours.

When

You might consider re-populating the search index if:

• Records seem to be missing from the user interface
• No records are showing in search or browse at all
• You have recently imported records from the command-line
• You have added a new language via the user interface Admin settings
• You have tried to perform an operation via the user interface that lead to a timeout

Basic usage

php symfony search:populate

For more information and additional options, see:

• Populate search index

Clearing the application cache¶

What

The Symfony 1.x framework that AtoM is built upon includes the ability to cache HTML content, for better responsiveness to HTTP requests.

One of the ways to speed up an application is to store chunks of generated HTML code, or even full pages, for future requests. This technique is known as caching, and it can be managed on the server side and on the client side.

…The principle of HTML caching is simple: Part or all of the HTML code that is sent to a user upon a request can be reused for a similar request. This HTML code is stored in a special place (the cache/ folder in symfony), where the front controller will look for it before executing an action. If a cached version is found, it is sent without executing the action, thus greatly speeding up the process. If no cached version is found, the action is executed, and its result (the view) is stored in the cache folder for future requests.”

From the Symfony docs

Occasionally, when errors occur or changes have been made, we need to flush the cached HTML so we are being served updated content, and not an outdated version of a web page. Running the cache:clear command will empty out the existing application cache so it will become repopulated overtime with updated versions of the web pages in AtoM as they are served to you.

When

You might want to try clearing the application cache if:

• You have made changes to AtoM’s configuration files
• You have recently encountered an error, and are testing to see if it’s resolved
• You are seeing something outdated or unexpected in the user interface
• You want to ensure you are seeing the current version of a page
• You have gotten a blank screen error that mysteriously works fine when the application is in Debug mode

Basic usage

php symfony cc

For more information, see: Clear cache

Rebuilding the nested set¶

What

AtoM generally uses a relational database to store its data (generally, MySQL). However, relational databases, which are comprised of flat tables, are not particularly suited to handling hierarchical data.

As developer Mike Hillyer notes, “Hierarchical data has a parent-child relationship that is not naturally represented in a relational database table.” One method of addressing this is to employ a “Nested set model” (Wikipedia).

AtoM makes use of a nested set to manage hierarchical relationships, such as between parent and child terms and descriptions. Sometimes, during operations that involve updates to large hierarchies, the nested set can become corrupted - especially if the server times out during an operation that reaches the execution limit settings. This task will rebuild all nested sets in AtoM.

When

You might consider rebuilding the nested set if:

• You are seeing strange behavior and/or missing records in the treeview
• You have attempted a long-running task that has timed out, causing it to fail midway
• You have gotten a 500 error, and the web server logs include something like: Parent Resource id: 'XXXXX' does not exist

Basic usage

php symfony propel:build-nested-set

For more information, see: Rebuild the nested set

Generating slugs¶

What

A slug is a word or sequence of words which make up the last part of a URL in AtoM. It is the part of the URL that uniquely identifies the resource and often is indicative of the name or title of the page (e.g.: in www.yourwebpage.com/about, the slug is about). The slug is meant to provide a unique, human-readable, permanent link to a resource. You can read more about slugs in AtoM here: Notes on slugs in AtoM.

In some cases, AtoM may time out in the middle of an operation that involves the creation of new records. In such cases, it is possible that AtoM has died after creating an information object, but before having a chance to create a slug for the record. This can cause unexpected errors in the application - most notably, 500 errors when trying to access the records missing slugs through the application interface. This task will generate new slugs for any that are missing them in the database.

When

You might want to try re-generating slugs if:

• You have timed out while attempting an operation that creates new records, such as an import, or saving a large description
• You have gotten an error or warning while trying to populate the search index with a message that includes something like: “Couldn’t find information object (id: XXXXX)”
• You suspect the error you’ve encountered may be due to data corruption
• You have made changes to the description permalink settings and want to update existing slugs to match these settings

Basic usage

php symfony propel:generate-slugs

For more information, see: Generate slugs

Back to top

Data corruption in information objects¶

The most common forms of database corruption among information objects (AKA archival descriptions) in AtoM tend to be due to one of the following:

• Missing slug
• Missing publication status ID value
• Missing object row values

You can use SQL to check the status of your information objects and see if all necessary values are present.

The following SQL query will output a 4-column table of information objects - the columns include the information object ID, the object ID, the publication status ID, and the slug for all descriptions. If any of the resulting rows are missing values, this will cause the search population task to throw warnings, and may cause other unexpected errors.

SELECT io.id as io_id, obj.id as obj_id, st.status_id as pub_status_id, slug.slug
  FROM information_object io
  LEFT JOIN object obj ON io.id=obj.id
  LEFT JOIN status st ON io.id=st.object_id AND st.type_id=158
  LEFT JOIN slug ON slug.object_id=io.id;

The resulting output should look something like this:

If you see rows with missing slugs, you can use the slug generation task to resolve this. See above - Generating slugs.

If you see rows with missing publication status ID values, then you can use SQL to replace these values for each missing instance. You will need to know the information object ID for the target row (listed in the first column of the table shown above). In the following example query, XXXXX represents where the object ID should be added. The third value, represented by YYY in the example below, will be the publication status ID value - use 159 to mark the target record as Draft, and 160 to mark the target record as Published.

INSERT INTO status (object_id, type_id, status_id, id, serial_number)
  VALUES ('XXXXX', '158', 'YYY', NULL, '0');

For example, if you found a row with an information object ID value of 35777 that was missing a publication status, and you wanted to mark it as Draft:

INSERT INTO status (object_id, type_id, status_id, id, serial_number)
  VALUES ('35777', '158', '159', NULL, '0');

If you see rows with a missing object ID then congratulations, you have encountered a rarer form of data corruption! You have two options for addressing this issue.

The first option is to simply delete the entire row in AtoM - this should cascade across other related tables. This solution will only work if the target row is not a parent record of other descriptions.

To delete the affected row, you will need to know the information object ID for the target row (listed in the first column of the table shown above). In the following example query, XXXXX represents where the object ID should be added:

DELETE FROM information_object WHERE id=XXXXX;

For example, if you wanted to delete an information object with an io_id value of 39447, enter:

DELETE FROM information_object WHERE id=39447;

We recommend that after deleting the affected row via SQL you rebuild the nested set to resolve any corruption in the hierarchy resulting from your changes.

The second option is to manually insert an object row for the affected record. To do so, you will need to give it a creation date and time, a last-modified date and time, and you’ll need to know the information object ID of the target record. The created_at and updated_at values can be made up or approximated, and they can also be the same if that’s easier. In the following example query, replace YYYY-MM-DD hh:mm:ss with your chosen created_at and updated_at values, and replace XXXXX with the information object ID of the target record:

INSERT INTO object (class_name, created_at, updated_at, id, serial_number)
  VALUES ('QubitInformationObject', 'YYYY-MM-DD hh:mm:ss', 'YYYY-MM-DD hh:mm:ss', 'XXXXX', '0');

For example, if you wanted to say your information object was created on January 1st, 2016 at 1pm, last updated on February 25th, 2018 at 11:45am, and it has an information object ID of 63172, then you could construct the SQL query like so:

INSERT INTO object (class_name, created_at, updated_at, id, serial_number)
  VALUES ('QubitInformationObject', '2016-01-01 13:00:00', '2018-02-25 11:45:00', '63172', '0');

Again, we recommend that after making these changes you rebuild the nested set to resolve any corruption in the hierarchy resulting from your changes.

Finally, there is one other data corruption edge case which can happen in rare circumstances: when an information object ends up with a duplicated publication status.

You can check for descriptions with a duplicated publication status in your database with the following query:

SELECT
 st.object_id, st.type_id, st.status_id
 FROM status st
     INNER JOIN (SELECT
                     object_id, type_id, COUNT(*) AS count
                     FROM status
                     WHERE type_id=158
                     GROUP BY object_id, type_id
                     HAVING COUNT(*)>1
                 ) dt ON st.object_id=dt.object_id and st.type_id=dt.type_id;

The following query can then be used to remove one of the duplicated publication statuses from the affected records. In the following example, we will remove the draft status with the publication status ID value of 159 in the last part of the query - to remove duplicated published statuses, change this value to 160:

DELETE st1
  FROM status as st1, status as st2
    WHERE
         st1.object_id = st2.object_id
      AND st1.type_id = st2.type_id
      AND st1.id > st2.id
      AND st1.type_id = 158
      AND st1.status_id = 159;

As with the other examples above, we recommend that after making these changes you rebuild the nested set to resolve any corruption in the hierarchy resulting from your changes.

Data corruption in other entities¶

As noted above, data corruption can potentially occur in any entity type in AtoM, but it is beyond the scope of this documentation to provide a solution to every possible issue. If you think you are encountering data corruption in another entity type in AtoM, you’ll need to do some research! We have collected some resources below to assist you.

First, we make copies of the AtoM database’s Entity Relationship Diagrams (ERDs) available on the AtoM wiki. An ERD is a data modelling technique that graphically illustrates an information system’s entities and the relationships between those entities. The AtoM ERDs can help you understand what tables exist in the AtoM database and how they are related. You can find them on our wiki here:

• https://wiki.accesstomemory.org/Development/ERDs

We also have some slides that will introduce you to using SQL queries in AtoM, available here:

• https://www.slideshare.net/accesstomemory/constructing-sql-queries-for-atom

There are also several utilities that can be used to provide a graphical user interface when exploring AtoM’s MySQL database. Two popular utilities that have been successfully used with AtoM include:

• MySQL Workbench: https://www.mysql.com/products/workbench/
• PHPMyAdmin: https://www.phpmyadmin.net/

Finally, be sure to double-check the MySQL reference documentation for your version for further tips on constructing SQL queries.

Below are a few extra SQL queries that might be useful when troubleshooting data corruption in other entity types.

Repository records

Finding a repository object ID when you know the slug:

SELECT object_id FROM slug WHERE slug='your-institution-slug';

Terms

Return the ID of all terms in a particular taxonomy (replace Taxonomy name in the example below with the name of the target taxonomy):

SELECT term.id, term_i18n.name
  FROM term
  LEFT JOIN term_i18n ON (term.id = term_i18n.id)
  WHERE term.taxonomy_id = (SELECT id FROM taxonomy_i18n WHERE culture = 'en'
  AND name = 'Taxonomy name') AND term_i18n.culture = 'en';

Return the number of times a term is linked to a description, sorting terms from most used to least. This will return all terms across taxonomies - if you want to see only one particular term, uncomment (aka remove the # at the start of the line) the WHERE line and add the target term ID in place of the XXX:

SELECT DISTINCT term_id, term_i18n.name, count(term_id) AS CountOf
  FROM object_term_relation
  JOIN term_i18n ON term_i18n.id = term_id and term_i18n.culture = 'en'
  #WHERE term_id = XXX
  GROUP BY term_id
  ORDER BY CountOf desc;

Back to top

Why do I get a blank white screen?¶

A blank, white screen in AtoM means that an error has occurred when loading the page. AtoM usually suppresses error messages in production mode for security reasons, so the first thing to do is put the application in Debug mode, then re-try whatever you were doing when you got the white screen. See:

• Debug mode
• Error logs and Debug mode

If the page loads with no errors in Debug mode, then you probably just need to clear the application cache to fix the regular (not in debug mode) webpage. See:

• Clear cache
• Clearing the application cache

If you get an error message, please see if it is addressed below.

If you still get a blank, white screen you will have to check your web server error log for error messages. See:

• Web server logs
• Error logs and Debug mode

Why do I get a 500 (Internal Server) error?¶

The 500 error is a very general HTTP status code that indicates a problem in the web server. You will need to check your web server error logs first, to get more information about the nature of the error. See:

• Web server logs
• Error logs and Debug mode

One common cause of 500 errors in AtoM is when AtoM attempts to run an asynchronous, but the job scheduler is not running as expected. You will know this is the case if you see the following message in the webserver error log:

"No Gearman worker available that can handle the job."

If this is the case, we recommend restarting the atom-worker and then re-trying the task that led to the 500 error. For more information on managing the atom-worker and the job scheduler, see:

• Asynchronous jobs and worker management
• Restarting the Job scheduler

If you’re not sure what to do with the error message you find, and it is not addressed in the other FAQ sections below, then you can collect as much information as you can, search the AtoM User Forum, and start a new thread if you are unable to find anything relevant that will help you resolve the issue. See:

• Figure out the nature of the problem
• Getting support

Why do I get a “Max execution time” exceeded error?¶

If you get an error like the following:

Fatal error: Maximum execution time of 60 seconds exceeded in ...

Then you may need to increase your PHP max_execution_time settings. See PHP script execution limits for instructions on how to change PHP settings:

• PHP execution limits
• Monitoring active processes and checking execution limits

Why do I get a “Allowed memory size” exhausted error?¶

If you get an error like the following:

Fatal error: Allowed memory size of 67108864 bytes exhausted (tried to allocate 233734 bytes) in ...

Then you may need to increase your PHP memory_limit settings. See PHP script execution limits for instructions on how to change PHP settings:

• PHP execution limits
• Monitoring active processes and checking execution limits

Why do I get a “Too many connections” error?¶

If you get an error like the following:

500 | Internal Server Error | PropelException

Unable to open PDO connection [wrapped: SQLSTATE[08004] [1040] Too many connections]

This is a problem in MySQL, please refer to its documentation - make sure you are looking at the correct documentation for the version of MySQL have have installed. Below is a relevant link for MySQL 8.0:

• https://dev.mysql.com/doc/refman/8.0/en/too-many-connections.html

Why do I get a “MySQL has gone away” error?¶

If you get an error like the following:

500 | Internal Server Error | PropelException

[wrapped: SQLSTATE[HY000]: General error: MySQL server has gone away

This is a problem in MySQL, please refer to its documentation - make sure you are looking at the correct documentation for the version of MySQL have have installed. Below is a relevant link for MySQL 8.0:

• https://dev.mysql.com/doc/refman/8.0/en/gone-away.html

It may be helpful to increase the level of verbosity in the MySQL logs to see if more details are available. From the MySQL documentation:

You can get more information about the lost connections by starting MySQL with the --log-warnings=2 option. This logs some of the disconnected errors in the hostname.err file. See Section 5.4.2, “The Error Log”:

• https://dev.mysql.com/doc/refman/8.0/en/error-log.html

Why do I get a “Parent Resource id: ‘XXXXX’ does not exist” error?¶

Usually this error is due to corruption of the nested set hierarchy of the resource (e.g. archival description, taxonomy term). This can usually be corrected by running the CLI task to rebuild the nested set:

php symfony propel:build-nested-set

For more details on this command, see:

• Rebuild the nested set

You may want to re-populate the search index and clear your application cache after as well. See:

• Populate search index
• Clear cache

If it still doesn’t work, then you may want to check for data corruption. See:

• Dealing with data corruption

Why do I get warnings when populating the search index?¶

If you’ve tried running the search:populate command (described in detail here), and you see the following warnings at the end of the console output:

Couldn't find information object (id: XXXXX)

Then Elasticsearch has encountered errors in your data, and was unable to find the listed information object IDs - consequently, these records have not been added to the search index, and will not be discoverable in the user interface via search and browse.

This warning suggests that there may be some corruption in your data. See the following section for further suggestions:

• Dealing with data corruption

You can also get basic configuration and status information about your search index with the following command-line task:

• Check the status of your Elasticsearch index

Why do I get a SearchPhaseExecutionException when trying to search?¶

If you get an error like the following:

500 | Internal Server Error |  Elastica\Exception\ResponseException

SearchPhaseExecutionException[Failed to execute phase [query_fetch], all shards failed]

This indicates an issue with Elasticsearch.

First, make sure that you have followed all the installation instructions for Elasticsearch, as outlined in our recommended installation documentation:

• Elasticsearch installation

You can get basic configuration and status information about your search index with the following command-line task:

• Check the status of your Elasticsearch index

You can try restarting Elasticsearch with the following:

sudo systemctl restart elasticsearch

You can then try re-populating the search index and clearing the cache. See:

• Populate search index
• Clear cache

If this doesn’t resolve the issue and/or you are unable to run the search:populate task, it may be that Elasticsearch is down. You can check the status and health of your ES cluster with the following command: :

curl -XGET 'http://localhost:9200/_cluster/health/?level=shards&pretty'

The status of shards must be green or yellow. If the status is any shard is red, you might want to try to restart Elasticsearch again.

The most common reason for ES failing to start is a lack of available system resources, such as not enough RAM, CPUs, and/or disk space. Elasticsearch also has its own configuration file - you might want to review the relevant ES set-up and configuration documentation:

• ES 1.7: https://www.elastic.co/guide/en/elasticsearch/reference/1.7/setup-configuration.html
• ES 5.x: https://www.elastic.co/guide/en/elasticsearch/reference/5.2/settings.html

For more information on troubleshooting Elasticsearch, see:

• Elasticsearch

Why do I get a 504 Connection timed out error?¶

A 504 Gateway timeout error usually means that the server acting as a gateway to handle the HTTP request is either down or too slow to fulfill the request. This can occur for a number of reasons, and it could be temporary so the first thing you might want to try is simply repeating the request.

If the 504 timeout reoccurs, we suggest first restarting services, clearing the application cache, and then monitoring your resources while repeating the action that lead to the timeout. For information on restarting services and clearing the application cache, see:

• Restarting services
• Clear cache

Monitoring your system resources and active processes in real-time while repeating the action can also provide you with more information about where the bottleneck is occurring that is leading to the timeout. For information on monitoring, see above:

• Monitoring active processes with htop

If you’re seeing spikes, then you may need to increase the available system resources (such memory, CPUs, and/or disk space).

You may also want to analyze your web logs - in many cases where we’ve seen significant slowdowns in AtoM it’s due to search engine web crawlers making a lot of requests in a short amount of time - often tens of thousands of requests a day. We’ve had good results with adding a robots.txt Crawl-delay to slow down requests (30 is a good initial value to try) and blocking particularly demanding or unwanted web crawlers. For more information, see:

• http://www.robotstxt.org/
• https://en.wikipedia.org/wiki/Robots_exclusion_standard
• https://www.google.com/webmasters/tools/robots-testing-tool

You can also look into increasing the execution limits configured for the site, so that more memory and time is made available before the limits are reached. More information can be found in the following sections:

• PHP execution limits

Why am I seeing strange behavior in the AtoM treeview?¶

If you’re using the Sidebar treeview, double-check your Treeview settings (in Admin > Settings > Treeview) and ensure the sort is set to “Manual”. There are known issues with the other sort options, particularly if you have any descriptions missing an identifier or a title. For more context on this particular issue, see the following issue ticket:

• https://projects.artefactual.com/issues/6574

If you’re using the Full-width treeview and you have recently used the drag-and-drop functionality to reorder sibling records in the treeview (described in the documentation here) and one of the moved records also has children, it’s possible that the background job to update the children has not yet completed. Wait a moment, and then refresh your browser. You can also check on the status of the job in the Jobs page - see:

• Manage jobs

If the job shows errors or refuses to complete, see the section above on Restarting the Job scheduler.

If none of the above is applicable, and/or you are still seeing issues, it could be that you need to rebuild the nested set. See:

• Rebuilding the nested set

You might want to clear all application caches after doing so, to ensure you are seeing the most up-to-date version of the page. See:

• Clear cache

Don’t forget to clear your web browser’s cache as well!

If there are still issues and you’ve tried all of the above, then it is possible you are encountering some data corruption. See the following section:

• Dealing with data corruption

Why can’t I upload (large) digital objects?¶

If you’re trying to upload digital objects via the user interface there are a couple things you can start to check. First, AtoM’s multi-file uploader (used to Upload multiple digital objects to archival descriptions at once) currently requires Flash to be installed and enabled in your web browser. If you can’t see any upload link, or you are constantly seeing an error in the widget when trying to upload an image, you may need to enable Flash.

Second, there have been reported issues with some browsers and the multi-uploader. Try using a different web browser and see if the outcome is different.

If the file is not huge but will not import via the user interface, you should double-check the various settings available in AtoM that can be used to limit the size and/or amount of digital objects. There is a global upload limit setting, and a per-institution upload limit setting. In both cases, set the limit to -1 for no limits on upload size. See:

• Default archival institution upload limit (GB)
• Set digital object upload limit for an archival institution

There is also a global upload limit maintained in one of AtoM’s configuration files - specifically, the config/app.yml file. You can also set this to -1 to disable upload limits. See:

• config/app.yml

If the file never uploads, or the process times out while attempting the upload, then the file itself may be too large to import via the user interface. One important thing to note is that currently, the digital object uploads are performed synchronously - that is, on-demand, in real time, via the web browser. Because most web browsers have a built in timeout limit of about 1 minute (to prevent long-running requests from consuming all resources like memory and crashing your browser), your upload may fail if the digital object is too big.

Note that during installation, there is also a 64MB limit on upload_max_filesize, which is maintained in your php.ini file. If you continue to experience timeouts or are running into this size limitation, then you may need to adjust your PHP execution limits. For more details, see:

• PHP execution limits

There are 2 alternative methods of importing digital objects - either with descriptive data in a CSV import, using the digitalObjectPath or digitalObjectURI columns, or using the command-line digitalobject:load task. These methods either make use of the job scheduler to perform the import asynchronously in the background, or they are performed via the terminal, avoiding the web browser and its timeout limits entirely. For more information, see:

CSV import documentation

• CSV import (user interface)
• Import CSV files via the command-line
• Digital object-related import columns

Digital object load task

• Load digital objects via the command line

If you are receiving errors during upload, or the upload is happening but there are no local copies (like the thumbnail in search results) available, please make sure you have the following dependencies installed:

• Other dependencies
• Other packages

If you have them installed, you can try regenerating your digital object derivatives with the following command:

php symfony digitalobject:regen-derivatives

For more detailed documentation on this command-line task, see:

• Regenerating derivatives

Why can’t I log into AtoM?¶

It could be that you’ve forgotten your correct password. If you need to reset it from the command-line, you can use the following task to change a user password:

• Change a password

Alternatively, you can temporarily create a new administrator account (AKA a “superuser”) via the command-line, so you can log in and update your previous password. You can then delete whichever account you no longer need from the command-line as well. See:

• Add a SuperUser (Admin) account
• Delete a user account from the command-line

If the login button is not showing, it could be that it is simply hidden in your theme. You can try navigating directly to the login page by adding /user/login to your base URL. For example, if your AtoM site is normally available at www.my-archives.com, try navigating to www.my-archives.com/user/login.

If you are simply redirected to the homepage instead of seeing a login screen, then there are a few possibilities. The first is that you have turned on AtoM’s “Require SSL for all administrator functionality” setting in Admin > Settings > Security, but you do not currently have your SSL certificate properly configured for your AtoM site, or are trying to login via HTTP instead of HTTPS. For more on this setting, see: Security panel. Similarly, it could be that you (or someone else) has configured IP whitelist restrictions via the Security panel - ensure you are logging in from a white-listed IP.

If you have accidentally turned on the “Require SSL” setting and can’t log in, it’s possible to use SQL to disable this setting. For basic information on accessing MySQL via the command-line, see: Accessing the MySQL command prompt. You will need to know the user and password you used for the database when installing AtoM, as well as the database name.

To use SQL to check and (if necessary) disable the SSL requirement setting, see:

• Enable or disable the SSL security setting

The other reason you might be getting booted back to the home page whenever you try to login is that it’s possible login for this installation is disabled via a setting in one of AtoM’s configuration files - specifically, the config/app.yml file.

Before you update this, double-check: is your installation using a 2-site deployment model (e.g. one internal read/write site, and a second public facing read-only catalog)? If yes, are you sure you are trying to log into the internal site, and not the public read-only site?

If you’ve checked that you’re trying to log into the correct site and you want to ensure that the read_only setting is not engaged in your edit site, then you will want to open the config/app.yml file via the command-line and ensure that the read_only setting is set to false. See:

• config/app.yml

What should I do if I get an error that isn’t described here?¶

First, please go through the above sections of this document. Collect as much information as you can about the nature of the issue and how to reproduce it, as well as information on your particular installation environment. See:

• Figure out the nature of the problem

Try restarting services, and/or some of the most common command-line tasks used for troubleshooting. See:

• Restarting services
• Running AtoM’s most common maintenance tasks

If these solutions don’t help, then you might want to search the AtoM user forum. Please review the following section of this document for tips on posting to the user forum:

• Getting support

Back to top