fix(ai-fal): handle errors from fal result fetch on completed jobs (#396)

* fix(ai-fal): handle FAILED queue status to prevent infinite polling

Map fal.ai's FAILED queue status to 'failed' instead of falling through
to the default case which incorrectly returned 'processing'. Unknown
statuses now also map to 'failed' as a safety net. Error details from
fal responses are surfaced in VideoStatusResult.error.

Closes #394

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(ai-fal): handle errors from fal result fetch on completed jobs

fal.ai never returns a FAILED queue status — invalid jobs go through
IN_PROGRESS → COMPLETED, and the real error (e.g. 422 validation)
only surfaces when calling fal.queue.result(). This extracts detailed
error info from the result fetch, removes the fictional FAILED status
handling, and returns failed status from getVideoJobStatus when the
result fetch throws.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* chore: update changeset to reflect actual fix

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: Alem Tuzlak <t.zlak@hotmail.com>

Author: 3 people

.changeset/fix-fal-failed-status.md

@@ -0,0 +1,8 @@
+---
+'@tanstack/ai-fal': patch
+'@tanstack/ai': patch
+---
+
+fix: handle errors from fal result fetch on completed jobs
+
+fal.ai does not return a FAILED queue status — invalid jobs report COMPLETED, and the real error (e.g. 422 validation) only surfaces when fetching results. `getVideoUrl()` now catches these errors and extracts detailed validation messages. `getVideoJobStatus()` returns `status: 'failed'` when the result fetch throws on a "completed" job.

packages/typescript/ai-fal/package.json

@@ -41,7 +41,7 @@
     "video-generation"
   ],
   "dependencies": {
-    "@fal-ai/client": "^1.9.1"
+    "@fal-ai/client": "^1.9.4"
   },
   "devDependencies": {
     "@tanstack/ai": "workspace:*",

packages/typescript/ai-fal/src/adapters/video.ts

@@ -31,6 +31,10 @@ interface FalVideoResultData {
 
 /**
  * Maps fal.ai queue status to TanStack AI video status.
+ *
+ * Note: fal.ai does not return a FAILED queue status. Errors surface
+ * as exceptions when fetching results from a COMPLETED job (e.g. 422
+ * validation errors). Those are handled in getVideoUrl().
  */
 function mapFalStatusToVideoStatus(
   falStatus: FalQueueStatus,
@@ -114,9 +118,26 @@ export class FalVideoAdapter<TModel extends FalModel> extends BaseVideoAdapter<
   }
 
   async getVideoUrl(jobId: string): Promise<VideoUrlResult> {
-    const result = await fal.queue.result(this.model, {
-      requestId: jobId,
-    })
+    let result
+    try {
+      result = await fal.queue.result(this.model, {
+        requestId: jobId,
+      })
+    } catch (error: any) {
+      // fal.ai may report COMPLETED status but throw on result fetch
+      // (e.g. 422 validation errors). Extract the detailed error info.
+      const detail = error?.body?.detail
+      if (Array.isArray(detail)) {
+        const messages = detail.map(
+          (d: { msg?: string; loc?: Array<string> }) =>
+            d.loc ? `${d.loc.join('.')}: ${d.msg}` : d.msg,
+        )
+        throw new Error(`Video generation failed: ${messages.join('; ')}`)
+      }
+      throw new Error(
+        `Failed to retrieve video result: ${error.message || error}`,
+      )
+    }
 
     const data = result.data as FalVideoResultData
 

packages/typescript/ai-fal/tests/video-adapter.test.ts

@@ -199,6 +199,18 @@ describe('Fal Video Adapter', () => {
 
       expect(result.status).toBe('completed')
     })
+
+    it('returns processing for unknown statuses', async () => {
+      mockQueueStatus.mockResolvedValueOnce({
+        status: 'UNKNOWN_STATUS',
+      })
+
+      const adapter = createAdapter()
+
+      const result = await adapter.getVideoStatus('job-unknown')
+
+      expect(result.status).toBe('processing')
+    })
   })
 
   describe('getVideoUrl', () => {
@@ -236,6 +248,29 @@ describe('Fal Video Adapter', () => {
       expect(result.url).toBe('https://fal.media/files/video2.mp4')
     })
 
+    it('throws detailed error when result fetch returns validation error', async () => {
+      mockQueueResult.mockRejectedValueOnce({
+        name: 'ValidationError',
+        status: 422,
+        message: 'Unprocessable Entity',
+        body: {
+          detail: [
+            {
+              type: 'string_too_long',
+              loc: ['body', 'prompt'],
+              msg: 'String should have at most 2500 characters',
+            },
+          ],
+        },
+      })
+
+      const adapter = createAdapter()
+
+      await expect(adapter.getVideoUrl('job-failed')).rejects.toThrow(
+        'Video generation failed: body.prompt: String should have at most 2500 characters',
+      )
+    })
+
     it('throws error when video URL is not found', async () => {
       mockQueueResult.mockResolvedValueOnce({
         data: {},

packages/typescript/ai/src/activities/generateVideo/index.ts

@@ -427,25 +427,25 @@ export async function getVideoJobStatus<
         url: urlResult.url,
       }
     } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : 'Failed to get video URL'
       aiEventClient.emit('video:request:completed', {
         requestId,
         provider: adapter.name,
         model: adapter.model,
         requestType: 'status',
         jobId,
-        status: statusResult.status,
+        status: 'failed',
         progress: statusResult.progress,
-        error:
-          error instanceof Error ? error.message : 'Failed to get video URL',
+        error: errorMessage,
         duration: Date.now() - startTime,
         timestamp: Date.now(),
       })
-      // If URL fetch fails, still return status
+      // Provider reported completed but result fetch failed — treat as failed
       return {
-        status: statusResult.status,
+        status: 'failed' as const,
         progress: statusResult.progress,
-        error:
-          error instanceof Error ? error.message : 'Failed to get video URL',
+        error: errorMessage,
       }
     }
   }