C3 AI Documentation Home

Troubleshooting Common Issues

Dump and export application state

View all environment info, retriever info, structured data configs, query engine configs, REA configs, and project configs.

Genai.TroubleshootUtil.exportAppState()

Query fails

Environment crashes

Ensure leader nodes have at least 100GB of disk space to accommodate Python runtime installation.

Debugging steps

Check the error message of the last failed query

Text
lastFailedQuery = Genai.Query.Result.fetch({filter:"failed==true", limit:1, order:"descending(meta.created)"});
engineLog = lastFailedQuery.parseEngineLog().parsedEngineLog;
c3DL(engineLog, 'json', 'failedQueryEngineLog.json')

Query returns unexpected answer

Check execution details

Inspect the engine log of the last query to review chain-of-thought reasoning, retrieved data, and execution details:

Text
lastQuery = Genai.Query.Result.fetch({limit:1, order:"descending(meta.created)"});
engineLog = lastQuery.parseEngineLog().parsedEngineLog;

Opensearch logs

Enable debug-level logs to diagnose complex issues:

For a specific Type (use the Type name):

Text
C3.Logger.for('Genai.Agent.Tool').setLogLevel('DEBUG')

For a Python file (use the file name but omit the “.py”):

Text
C3.Logger.for('document_parser').setLogLevel('DEBUG')

Stuck or slow query

To diagnose bottlenecks, check the following:

Action Dump

Use Action.dump() to inspect child actions during execution.

OpenSearch Logs

  • Look for long-running actions with t_type:Genai.ChatBot and t_action:query.
  • In the left-hand panel, select the event.original field for display.
  • Filter by a_t > X to isolate slow queries.
  • Group actions by the same root ID (a_rid) to track execution time of child actions.
  • Sort by execution time to identify bottlenecks.

Config updates not applying

If setConfig or setConfigValue isn't updating the config, it may have issues preventing changes. Check for issues by running:

Js.exec(<config>.getConfig().issues)

Data Ingestion

Confirm the chunker configuration

Use the Mew3 chunker to process files. Mew3 is a chunker designed to support multimodal PDF parsing. It segments documents into structured, meaningful units using the layout structure to extract text, images, and tables. Mew3 improves the quality and consistency of parsing by integrating layout-based segmentation directly into the parsing pipeline.

Update your configuration using the C3 AI Application Initialization

Incorrect chunker configuration can cause indexing failures. For supported formats and capabilities, see the Multi-modal PDF parsing.

Follow these steps to confirm the chunker assigned to a file type.

Check the chunker for a file type

  1. Open the Application C3 AI Console.

  2. Run the following command:

    JavaScript
    var chunkerConfig = Genai.SourceFile.Chunker.UniversalChunker.Config.forConfigKey('default');
var fileExtToChunkerSpecMap = C3.Map.fromJson(chunkerConfig.fileExtToChunkerSpecMap);
fileExtToChunkerSpecMap.get('.pdf').get('chunker');

  3. Review the output to identify the chunker. The output should display Genai.SourceFile.Chunker.Mew3, confirming that Mew3 is active.

Investigate indexing failures

Verify that the chunker is correctly configured. Then use the steps below to identify issues in indexing.

Check error message on source file

Run the following to fetch the most recent failed source file:

JavaScript
lastFailedSourceFile = Genai.SourceFile.fetch({
        filter: "status.value == 'Failed'",
        order : "descending(meta.created)",
        limit:1
}).first();
console.log(lastFailedSourceFile.status.errorMessage);

Check BatchQueue, MapReduceQueue, and ActionQueue if the error message does not appear. 1Code has comments. Press enter to view.

Resolve common failure modes

  • Provide files that contain extractable text. Scanned PDFs are not supported.

  • Restart the Python service on the indexer node if the process dies with exit code 137.

  • Reset the vector store and restart the indexer node to resolve unknown failures:

    JavaScript
    ActionQueue.clear();
indexerNoder.callJson("Server","restart");

Investigate stuck indexing

Use the commands below to examine indexing progress if the process begins but does not finish.

Check the indexing queue

  • Retrieve invalidation queue counts:

    JavaScript
    c3Grid(InvalidationQueue.countAll());

  • View pending ActionQueue entries:

    JavaScript
    c3Grid(C3.app().nodes());
// then check node pool configuration
retriever.indexerNodePoolMatrix;

  • View processing entries:

    JavaScript
    indexerNode.callJson("Action", "dump");

Address indexing failure modes

  • Verify that the indexer node is running. Run the following to check node logs:

    JavaScript
    c3Grid(C3.app().nodes());

  • Scale the environment and enable GPU support when processing large document volumes.

Investigate ingestion-specific failures

Review ingestion logs when indexing and chunking complete without errors.

Check data ingestion status

View the ingestion status:

JavaScript
c3Grid(DataIntegStatus.fetch({ order: "descending(meta.created)" }));

Use the network tab in the UI to identify call errors if the logs show no issues.

Verify passage content in source files

Ensure the application extracts passages from indexed files as expected.

  1. Fetch all chunked and indexed source files:

    JavaScript
    Genai.SourceFile.fetch();

  2. View passages for a specific file:

    JavaScript
    myFileName = "<your_file_name>";
Genai.SourceFile.fetch({
    filter:`exists(passagesFile) && contains(originalFile.url, '${myFileName}')`,
    limit:1
}).first().readPassages();
Was this page helpful?