Fix BUILD-1144: Prevent Neynar API 20-character limit error

src/db/services/users-service.ts

@@ -764,6 +764,27 @@ export class UsersService {
 
     logger.debug(`🔍 DEBUG: Cleaned username: "${cleanUsername}"`);
 
+    // Validate input length - Neynar API requires q parameter to be 20 characters or less
+    if (cleanUsername.length > 20) {
+      // Check if it looks like an Ethereum address
+      if (cleanUsername.startsWith('0x') && cleanUsername.length === 42) {
+        logger.debug(`❌ DEBUG: Ethereum address search not supported: "${cleanUsername}"`);
+        return {
+          success: true,
+          users: [],
+          error: 'Address-based search is not supported. Please search by username instead.',
+        };
+      }
+
+      // Generic long string error
+      logger.debug(`❌ DEBUG: Search query too long (${cleanUsername.length} chars, max 20): "${cleanUsername}"`);
+      return {
+        success: true,
+        users: [],
+        error: 'Search query must be 20 characters or less. Please use a shorter search term.',
+      };
+    }
+
     try {
       // Use Neynar search endpoint for fuzzy matching
       if (!this.neynarApiKey) {

src/routes/users.ts

@@ -423,6 +423,15 @@ users.post('/search', requirePermission('read'), async c => {
     return c.json({ error: result.error || 'Search failed' }, 500);
   }
 
+  // Handle validation errors (e.g., search term too long, address search)
+  if (result.error) {
+    return c.json({ 
+      error: result.error,
+      users: result.users || [],
+      hint: 'Try searching with a shorter username or handle'
+    }, 400);
+  }
+
   // For each user result, create or get the user to ensure we have their database ID
   const usersWithDbIds = await Promise.all(
     (result.users || []).map(async user => {

tests/services/users-service.test.ts

@@ -464,6 +464,40 @@ describe('UsersService', () => {
       expect(result.users!.length).toBe(1);
       expect(result.users![0].username).toBe('vitalik.eth');
     });
+
+    // BUILD-1144 fix: Test validation for search queries longer than 20 characters
+    it('should handle Ethereum address search with appropriate error message', async () => {
+      const ethereumAddress = '0x0B5f5a722Ac5E8EcEDf4da39A656fe5f1e76b34C';
+      const result = await usersService.searchUsersByUsername(ethereumAddress);
+
+      expect(result.success).toBe(true);
+      expect(result.users).toBeDefined();
+      expect(Array.isArray(result.users)).toBe(true);
+      expect(result.users!.length).toBe(0);
+      expect(result.error).toBe('Address-based search is not supported. Please search by username instead.');
+    });
+
+    it('should handle long search queries with appropriate error message', async () => {
+      const longQuery = 'this-is-a-very-long-username-that-exceeds-twenty-characters';
+      const result = await usersService.searchUsersByUsername(longQuery);
+
+      expect(result.success).toBe(true);
+      expect(result.users).toBeDefined();
+      expect(Array.isArray(result.users)).toBe(true);
+      expect(result.users!.length).toBe(0);
+      expect(result.error).toBe('Search query must be 20 characters or less. Please use a shorter search term.');
+    });
+
+    it('should handle search queries exactly at 20 character limit', async () => {
+      const exactLimitQuery = '12345678901234567890'; // exactly 20 chars
+      const result = await usersService.searchUsersByUsername(exactLimitQuery);
+
+      // Should succeed without validation error (though may return empty results from API)
+      expect(result.success).toBe(true);
+      expect(result.users).toBeDefined();
+      expect(Array.isArray(result.users)).toBe(true);
+      expect(result.error).toBeUndefined(); // No validation error
+    });
   });
 
   describe('Service Configuration', () => {