Merge pull request #1032 from objectstack-ai/copilot/fix-record-detail-not-found

Author: hotlong

ROADMAP.md

@@ -1284,6 +1284,17 @@ Plugin architecture refactoring to support true modular development, plugin isol
 
 ## 🐛 Bug Fixes
 
+### Record Detail "Record Not Found" in External Metadata Environments (March 2026)
+
+**Root Cause:** Three compounding issues caused "Record not found" when navigating from a list to a record detail page in external metadata environments:
+1. `DetailView.tsx`'s alt-ID fallback only triggered when `findOne` returned null. If it threw an error (server 500, network failure, etc.), the error propagated to the outer catch handler and the fallback was never tried.
+2. `ObjectStackAdapter.findOne` with `$expand` used `rawFindWithPopulate` with `$filter: { _id: id }`, which some external servers don't support. On failure it threw, instead of falling back to the simpler `data.get()` call.
+3. Record IDs in navigation URLs were not URL-encoded, which could cause routing issues with IDs containing special characters.
+
+**Fix:** Made `DetailView` catch all errors from the first `findOne` (converting to null) so the alt-ID fallback always runs. Made `ObjectStackAdapter.findOne` fall through to direct `data.get()` when the `$expand` raw request fails with a non-404 error. Added `encodeURIComponent` for record IDs in all navigation URL construction points.
+
+**Tests:** 32 DetailView tests, 12 expand tests, 33 useNavigationOverlay tests, 6 RecordDetailEdit tests — all pass.
+
 ### Auth Registration and Login Unavailable in MSW/Server Modes (March 2026)
 
 **Root Cause:** `createKernel.ts` (MSW mode) and `objectstack.config.ts` (Server mode) did not load `AuthPlugin`, so the kernel had no 'auth' service. All `/api/v1/auth/*` endpoints (sign-up, sign-in, get-session, sign-out) returned 404.

apps/console/src/components/ObjectView.tsx

@@ -436,17 +436,17 @@ export function ObjectView({ dataSource, objects, onEdit }: any) {
             if (action === 'new_window') {
                 // Open record detail in a new browser tab with Console-correct URL
                 const basePath = window.location.pathname.replace(/\/view\/.*$/, '');
-                window.open(`${basePath}/record/${String(recordId)}`, '_blank');
+                window.open(`${basePath}/record/${encodeURIComponent(String(recordId))}`, '_blank');
                 return;
             }
             // page / view mode — navigate to record detail page
             // Handles action === 'view' (from useNavigationOverlay page mode) and
             // default fallthrough for any unrecognised action
             if (action === 'view' || !action || action === 'page') {
                 if (viewId) {
-                    navigate(`../../record/${String(recordId)}`, { relative: 'path' });
+                    navigate(`../../record/${encodeURIComponent(String(recordId))}`, { relative: 'path' });
                 } else {
-                    navigate(`record/${String(recordId)}`);
+                    navigate(`record/${encodeURIComponent(String(recordId))}`);
                 }
             }
         },
@@ -669,9 +669,9 @@ export function ObjectView({ dataSource, objects, onEdit }: any) {
                 onEdit?.({ _id: recordId, id: recordId });
             } else if (mode === 'view') {
                 if (viewId) {
-                    navigate(`../../record/${String(recordId)}`, { relative: 'path' });
+                    navigate(`../../record/${encodeURIComponent(String(recordId))}`, { relative: 'path' });
                 } else {
-                    navigate(`record/${String(recordId)}`);
+                    navigate(`record/${encodeURIComponent(String(recordId))}`);
                 }
             }
         },

apps/console/src/hooks/useObjectActions.ts

@@ -127,7 +127,7 @@ export function useObjectActions({
 
   const navigateToRecord = useCallback(
     (recordId: string) => {
-      navigate(`${baseUrl}/${objectName}/record/${recordId}`);
+      navigate(`${baseUrl}/${objectName}/record/${encodeURIComponent(recordId)}`);
     },
     [navigate, baseUrl, objectName],
   );

packages/data-objectstack/src/expand.test.ts

@@ -177,6 +177,28 @@ describe('ObjectStackAdapter $expand support', () => {
 
       expect(result).toBeNull();
     });
+
+    it('should fall through to data.get() when $expand raw request fails with non-404 error', async () => {
+      // The raw populate request fails (e.g., server doesn't support the filter+populate API)
+      mockFetch.mockResolvedValue({
+        ok: false,
+        status: 500,
+        statusText: 'Internal Server Error',
+        json: () => Promise.resolve({ message: 'unsupported' }),
+      });
+      // But the direct data.get() call succeeds
+      mockClient.data.get.mockResolvedValue({ record: { _id: 'order-1', name: 'Order 1' } });
+
+      const result = await adapter.findOne('order', 'order-1', {
+        $expand: ['customer'],
+      });
+
+      // Should have tried raw request first
+      expect(mockFetch).toHaveBeenCalled();
+      // Then fell through to data.get()
+      expect(mockClient.data.get).toHaveBeenCalledWith('order', 'order-1');
+      expect(result).toEqual({ _id: 'order-1', name: 'Order 1' });
+    });
   });
 
   describe('raw request format', () => {

packages/data-objectstack/src/index.ts

@@ -300,7 +300,9 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
         if ((error as Record<string, unknown>)?.status === 404) {
           return null;
         }
-        throw error;
+        // Fall through to direct GET without $expand — some servers don't
+        // support the filter+populate API, so gracefully degrade to a
+        // simple data.get() call below rather than failing with "Record not found".
       }
     }
 

packages/plugin-detail/src/DetailView.tsx

@@ -130,14 +130,8 @@ export const DetailView: React.FC<DetailViewProps> = ({
           ? dataSource.findOne(objectName, resourceId, params)
           : dataSource.findOne(objectName, resourceId);
 
-        return findOnePromise.then((result) => {
-          if (!isMounted) return;
-          if (result) {
-            setData(result);
-            setLoading(false);
-            return;
-          }
-          // Fallback: try alternate ID format for backward compatibility
+        // Helper: try alternate ID format (strip or prepend objectName prefix)
+        const tryAltId = () => {
           const resIdStr = String(resourceId);
           const altId = resIdStr.startsWith(prefix)
             ? resIdStr.slice(prefix.length)   // strip prefix
@@ -156,6 +150,19 @@ export const DetailView: React.FC<DetailViewProps> = ({
               setLoading(false);
             }
           });
+        };
+
+        return findOnePromise
+          .catch(() => null) // Convert any error to null to trigger alternate ID fallback
+          .then((result) => {
+          if (!isMounted) return;
+          if (result) {
+            setData(result);
+            setLoading(false);
+            return;
+          }
+          // Fallback: try alternate ID format for backward compatibility
+          return tryAltId();
         });
       }).catch((err) => {
          if (isMounted) {

packages/plugin-detail/src/__tests__/DetailView.test.tsx

@@ -539,6 +539,37 @@ describe('DetailView', () => {
     expect(onBack).toHaveBeenCalled();
   });
 
+  it('should try fallback with alternate ID when first findOne throws an error', async () => {
+    let callCount = 0;
+    const mockDataSource = {
+      findOne: vi.fn().mockImplementation((_obj: string, id: string) => {
+        callCount++;
+        if (callCount === 1) {
+          // First call throws (simulate server error)
+          return Promise.reject(new Error('Server error'));
+        }
+        // Second call (fallback) succeeds
+        return Promise.resolve({ name: 'Alice' });
+      }),
+    } as any;
+
+    const schema: DetailViewSchema = {
+      type: 'detail-view',
+      title: 'Contact Details',
+      objectName: 'contact',
+      resourceId: 'contact-123',
+      fields: [{ name: 'name', label: 'Name' }],
+    };
+
+    const { findByText } = render(<DetailView schema={schema} dataSource={mockDataSource} />);
+    // The fallback should find the record using the stripped ID
+    expect(await findByText('Alice')).toBeInTheDocument();
+    // findOne should be called twice: first with original ID, then with stripped prefix
+    expect(mockDataSource.findOne).toHaveBeenCalledTimes(2);
+    expect(mockDataSource.findOne).toHaveBeenNthCalledWith(1, 'contact', 'contact-123');
+    expect(mockDataSource.findOne).toHaveBeenNthCalledWith(2, 'contact', '123');
+  });
+
   it('should call findOne with $expand when objectSchema has lookup fields', async () => {
     const mockDataSource = {
       getObjectSchema: vi.fn().mockResolvedValue({

packages/plugin-view/src/ObjectView.tsx

@@ -419,7 +419,7 @@ export const ObjectView: React.FC<ObjectViewProps> = ({
       }
       if (navigationConfig.mode === 'new_window' || navigationConfig.openNewTab) {
         const recordId = record._id || record.id;
-        const url = `/${schema.objectName}/${recordId}`;
+        const url = `/${schema.objectName}/${encodeURIComponent(String(recordId))}`;
         window.open(url, '_blank');
         return;
       }

packages/react/src/hooks/useNavigationOverlay.ts

@@ -147,7 +147,8 @@ export function useNavigationOverlay(
           return;
         }
         const viewPath = view ? `/${view}` : '';
-        const url = objectName ? `/${objectName}/${recordId}${viewPath}` : `/${recordId}${viewPath}`;
+        const encodedId = encodeURIComponent(String(recordId));
+        const url = objectName ? `/${objectName}/${encodedId}${viewPath}` : `/${encodedId}${viewPath}`;
         window.open(url, '_blank');
         return;
       }