Merge pull request #103 from aws-solutions-library-samples/fix/ui-doc-list-failure

Fix/UI doc list failure

Author: rstrahan

CHANGELOG.md

@@ -5,6 +5,15 @@ SPDX-License-Identifier: MIT-0
 
 ## [Unreleased]
 
+### Fixed
+
+- **UI Robustness for Orphaned List Entries** - [#102](https://github.com/aws-solutions-library-samples/accelerated-intelligent-document-processing-on-aws/issues/102)
+  - Fixed UI error banner "failed to get document details - please try again later" appearing when orphaned list entries exist (list# items without corresponding doc# items in DynamoDB tracking table)
+  - **Root Cause**: When a document had a list entry but no corresponding document record, the error would trigger UI banner and prevent display of all documents in the same time shard
+  - **Solution**: Enhanced error handling to gracefully handle missing documents - now only shows error banner if ALL documents fail to load, not just one
+  - **Enhanced Debugging**: Added detailed console logging with full PK/SK information for both list entries and expected document entries to facilitate cleanup of orphaned records
+  - **User Impact**: All valid documents now display correctly even when orphaned list entries exist; debugging information available in browser console for identifying problematic entries
+
 ## [0.3.21]
 
 ### Added

VERSION

@@ -1 +1 @@
-0.4.0-wip1
+0.4.0-wip2

lib/idp_common_pkg/pyproject.toml

@@ -126,6 +126,8 @@ test = [
   "pytest-asyncio>=1.1.0",
   "typer>=0.19.2",
   "ruff>=0.14.0",
+  "deepdiff>=6.0.0",                    # Required for BDA blueprint service tests
+  "datamodel-code-generator>=0.25.0",   # Required for schema/pydantic generator tests
 ]
 
 # Full package with all dependencies

src/ui/src/hooks/use-graphql-api.js

@@ -72,15 +72,39 @@ const useGraphQlApi = ({ initialPeriodsToLoad = DOCUMENT_LIST_SHARDS_PER_DAY * 2
         client.graphql({ query: getDocument, variables: { objectKey } }),
       );
       const getDocumentResolutions = await Promise.allSettled(getDocumentPromises);
+
+      // Separate rejected promises from null/undefined results
       const getDocumentRejected = getDocumentResolutions.filter((r) => r.status === 'rejected');
-      if (getDocumentRejected.length) {
-        setErrorMessage('failed to get document details - please try again later');
-        logger.error('get document promises rejected', getDocumentRejected);
+      const fulfilledResults = getDocumentResolutions.filter((r) => r.status === 'fulfilled');
+      const getDocumentNull = fulfilledResults
+        .map((r, idx) => ({ doc: r.value?.data?.getDocument, key: objectKeys[idx] }))
+        .filter((item) => !item.doc)
+        .map((item) => item.key);
+
+      // Log partial failures but NEVER show error banner for individual document failures
+      if (getDocumentRejected.length > 0) {
+        logger.warn(
+          `Failed to load ${getDocumentRejected.length} of ${objectKeys.length} document(s) due to query rejection`,
+        );
+        logger.debug('Rejected promises:', getDocumentRejected);
       }
+      if (getDocumentNull.length > 0) {
+        logger.warn(
+          `${getDocumentNull.length} of ${objectKeys.length} document(s) not found (returned null):`,
+          getDocumentNull,
+        );
+        logger.warn(
+          'These documents have list entries but no corresponding document records - possible orphaned list entries',
+        );
+      }
+
+      // Filter out null/undefined documents to prevent downstream errors
       const documentValues = getDocumentResolutions
         .filter((r) => r.status === 'fulfilled')
-        .map((r) => r.value?.data?.getDocument);
+        .map((r) => r.value?.data?.getDocument)
+        .filter((doc) => doc != null);
 
+      logger.debug(`Successfully loaded ${documentValues.length} of ${objectKeys.length} requested documents`);
       return documentValues;
     },
     [setErrorMessage],
@@ -256,11 +280,26 @@ const useGraphQlApi = ({ initialPeriodsToLoad = DOCUMENT_LIST_SHARDS_PER_DAY * 2
         const documentData = await documentDataPromise;
         const objectKeys = documentData.map((item) => item.ObjectKey);
         const documentDetails = await getDocumentDetailsFromIds(objectKeys);
-        // Merge document details with PK and SK
-        return documentDetails.map((detail) => {
-          const matchingData = documentData.find((item) => item.ObjectKey === detail.ObjectKey);
-          return { ...detail, ListPK: matchingData.PK, ListSK: matchingData.SK };
-        });
+
+        // Log orphaned list entries with full PK/SK details for debugging
+        const retrievedKeys = new Set(documentDetails.map((d) => d.ObjectKey));
+        const missingDocs = documentData.filter((item) => !retrievedKeys.has(item.ObjectKey));
+        if (missingDocs.length > 0) {
+          missingDocs.forEach((item) => {
+            logger.warn(`Orphaned list entry detected:`);
+            logger.warn(`  - List entry: PK="${item.PK}", SK="${item.SK}"`);
+            logger.warn(`  - Expected doc entry: PK="doc#${item.ObjectKey}", SK="none"`);
+            logger.warn(`  - ObjectKey: "${item.ObjectKey}"`);
+          });
+        }
+
+        // Merge document details with PK and SK, filtering out nulls to prevent shard-level failures
+        return documentDetails
+          .filter((detail) => detail != null)
+          .map((detail) => {
+            const matchingData = documentData.find((item) => item.ObjectKey === detail.ObjectKey);
+            return { ...detail, ListPK: matchingData.PK, ListSK: matchingData.SK };
+          });
       });
 
       const documentValuesPromises = documentDetailsPromises.map(async (documentValuesPromise) => {
@@ -279,9 +318,14 @@ const useGraphQlApi = ({ initialPeriodsToLoad = DOCUMENT_LIST_SHARDS_PER_DAY * 2
       setDocumentsDeduped(documentValuesReduced);
       setIsDocumentsListLoading(false);
       const getDocumentsRejected = getDocumentsPromiseResolutions.filter((r) => r.status === 'rejected');
-      if (getDocumentsRejected.length) {
+      // Only show error banner if ALL shard queries failed
+      if (getDocumentsRejected.length === documentDataPromises.length) {
         setErrorMessage('failed to get document details - please try again later');
-        logger.error('get document promises rejected', getDocumentsRejected);
+        logger.error('All shard queries rejected', getDocumentsRejected);
+      } else if (getDocumentsRejected.length > 0) {
+        // Partial failure - log but don't show error banner
+        logger.warn(`${getDocumentsRejected.length} of ${documentDataPromises.length} shard queries failed`);
+        logger.debug('Rejected shard queries:', getDocumentsRejected);
       }
     } catch (error) {
       setIsDocumentsListLoading(false);