Skip to main content

Indexing Issues

warning

This is a legacy checklist that will be replaced with structured troubleshooting guides. For comprehensive troubleshooting guidance, refer to the Troubleshooting Guides section.

FullIndexer Configuration Issues​

The FullIndexer may fail to process all index groups or encounter errors during execution. These issues typically stem from configuration problems or data consistency issues.

Common Configuration Problems​

The most frequent FullIndexer issues involve incorrect project settings or field mapping mismatches between the index configuration and database queries.

Verify that the FullIndexer is enabled in the project preferences by checking the indexsearchFullIndexerEnabled setting. The indexer cannot process any groups if this setting is disabled.

Enable debug logging by activating one of the following debug flags to capture detailed processing information:

  • INDEXSEARCH for general indexing operations
  • INDEXSEARCH_INDEXER for specific indexer activities
  • INDEXSEARCH_EXTENDED for comprehensive debug output

Field Mapping Validation​

Index field mappings must precisely match the SQL query structure to prevent processing errors.

Compare the IndexRecordFieldMappings in the RecordContainer with the SELECT statement columns in the corresponding SQL query. The order and number of fields must be identical in both configurations. Mismatched field counts or incorrect ordering will cause the indexer to fail or produce incomplete results.

When subprocess components access field values, verify that they reference the correct field positions within the RecordFieldMappings array. Position-based field access that references non-existent or incorrectly ordered fields will generate runtime errors.

Multi-Value Field Configuration​

Fields that receive multiple values during indexing must have the multiValued attribute enabled in the field definition. Attempting to index multiple values into a single-value field will cause indexing failures.

Review field definitions in the index schema to ensure that fields expecting arrays or multiple values are properly configured as multi-value fields.

Legacy Field Type Issues​

Legacy installations may encounter issues with LARGE_TEXT field types. Replace LARGE_TEXT field types with TEXT if indexing problems occur, as newer ADITO versions provide better support for the standard TEXT type.

Post-Configuration Steps​

After making configuration changes, follow this deployment sequence:

  1. Deploy the affected index groups and entities
  2. Execute ClearCache operation in the Manager twice with 1-2 second intervals
  3. Run the FullIndexer to process the updated configuration

Incremental Indexer Problems​

The incremental indexer relies on database audit functionality to detect changes and maintain index synchronization. Configuration issues in either the indexer or audit system will prevent automatic updates.

Indexer Activation Verification​

Confirm that incremental indexing is enabled in the project preferences. Navigate to Project Preferences → Modules → IndexSearch and verify that indexsearchIncrementingIndexerEnabled is active.

If the indexer remains inactive after enabling this setting, disable and re-enable the option to reset the indexer state.

Database Audit Configuration​

The incremental indexer requires properly configured database auditing to function correctly.

Audit System Activation​

Verify that the audit system is active by checking for the "Database audit activated" message in the server startup log. If this message does not appear, the audit configuration requires attention.

Configure audit mode for each relevant database table by accessing the data alias properties. Double-click the data alias in the project tree, select the target table in the Navigator, and set the appropriate auditMode value in the Properties panel.

Audit Configuration Errors​

Common audit configuration errors include missing ID columns and incomplete audit sync configurations.

Ensure that all database tables include an idColumn definition by reviewing the data alias configuration. Add missing ID columns through the Source tab if they are absent.

Verify that all tables contain complete auditSyncConfig entries by examining the alias XML structure.

Missing Audit Sync Configuration​

When the number of <entityDB> entries exceeds the number of <auditSyncConfig> entries in the data alias XML, manually add the missing configuration blocks.

Use this template for missing audit sync configurations:

<auditSyncConfig>
<name>auditSyncConfig</name>
<auditMode v="0" />
<syncActive v="false" />
<syncComplete v="false" />
<syncDirection v="1" />
<syncIds></syncIds>
</auditSyncConfig>

Insert the template after each <description> node that lacks a corresponding auditSyncConfig entry.

Process Validation​

The incremental indexer depends on two critical processes: the affected IDs process and the query process for each index group.

Affected IDs Process Verification​

The affectedIdsProcess must return correct unique identifiers for changed records. Verify that this process returns valid UIDs that correspond to the primary key values of modified database records.

Add logging statements to the affected IDs process to monitor the returned values and confirm they match the expected record identifiers.

Query Process Validation​

Each index group's query process must properly handle the unique identifiers provided by the affected IDs process.

Confirm that the SQL query includes appropriate restrictions using local.idvalue parameters and filters results to the primary key column. The query should return exactly one record for each provided identifier.

Verify that the query includes proper ordering with an ORDER BY clause and converts the final result using the .toString() method.

Check for common query issues such as:

  • Using JOIN instead of LEFT JOIN, which can exclude valid records
  • Missing primary key restrictions that cause multiple records to be returned
  • Undefined variables that lack proper var or let declarations

Architecture-Specific Issues​

Cloud deployments using background servers with embedded indexes cannot support incremental indexing. These configurations require migration to remote index services to enable proper incremental functionality.

Verify that background server deployments use remote Solr services rather than embedded index configurations.

Global Incremental Indexer Issues​

When no index groups receive incremental updates, check these system-level configurations:

Confirm that the database audit system is enabled in the instance configuration and that the incremental indexer interval is set to a value greater than zero in the project preferences.

For cloud deployments, verify that background servers use compatible index configurations and that the incremental indexer service is properly initialized.

Individual Index Group Problems​

When specific index groups fail to receive incremental updates while others function correctly, focus on group-specific configuration issues.

Review the affected IDs process for the problematic index group by adding logging statements to verify that the process returns expected identifier values.

Examine the SQL query for the index group to ensure proper JOIN relationships and primary key filtering. Replace unnecessary JOIN operations with LEFT JOIN to prevent record exclusion.

important

Always execute a FullIndexer run after resolving incremental indexer issues to ensure that any missed updates are properly synchronized to the index.

Problem isn't solved?​

For additional troubleshooting guidance on specific indexing scenarios, refer to these specialized guides: