fix: lazy-compile server fn on dev restart to avoid invalid ID error by schiller-manuel · Pull Request #6655 · TanStack/router

schiller-manuel · 2026-02-14T00:47:09Z

Summary by CodeRabbit

Bug Fixes
- Improved runtime validation and error handling for server functions in development mode with enhanced lazy-loading behavior.

coderabbitai · 2026-02-14T00:47:23Z

📝 Walkthrough

Walkthrough

This change implements runtime lazy-validation for server function IDs in development mode. When a server function ID isn't immediately registered, the handler now decodes the base64url-encoded ID to extract file and export information, fetches the module to trigger compilation, then re-checks the registry.

Changes

Cohort / File(s)	Summary
Server Function Lazy-Loading `packages/start-plugin-core/src/start-compiler-plugin/plugin.ts`	Added async handler with runtime lazy-validation flow for unregistered server function IDs. Decodes base64url IDs, resolves absolute paths, triggers module compilation, and rechecks registry. Introduced imports for `assert` and path `resolve`. Adjusted error handling to use extracted fnId.

Sequence Diagram

sequenceDiagram
    participant Client
    participant Handler as Dev Handler
    participant Registry as serverFnsById
    participant Decoder as Base64 Decoder
    participant Resolver as Path Resolver
    participant Loader as Module Loader
    
    Client->>Handler: Request with server function ID
    Handler->>Registry: Check if ID is registered
    alt ID Found
        Registry-->>Handler: Return function
        Handler-->>Client: Success
    else ID Not Found
        Handler->>Decoder: Decode base64url ID
        alt Decode Success
            Decoder-->>Handler: Extract file & export
            Handler->>Resolver: Resolve to absolute path
            Resolver-->>Handler: Return absolute path
            Handler->>Loader: Fetch module (trigger compilation)
            Loader-->>Handler: Module loaded
            Handler->>Registry: Re-check registry
            alt Now Registered
                Registry-->>Handler: Return function
                Handler-->>Client: Success
            else Still Missing
                Handler-->>Client: Error - function not found
            end
        else Decode/Fetch Fails
            Handler-->>Client: Error - invalid ID
        end
    end

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

fix: no invalidation for server functions in dev #5513: Addresses dev-time server-function ID resolution/invalidation; the main PR's lazy validation flow that forces module fetch directly relates to fixes around server function manifest and dev invalidation.
fix: validate server fn id during dev #6087: Implements runtime validation/lazy loading of server function IDs in development with assertion and decoding logic, mirroring the approach in this PR.
fix: dev serverfn resolution on windows #5520: Touches dev-time server function ID resolution and async lookup flows for serverFnsById, sharing similar concerns with this change.

Suggested labels

package: start-plugin-core

Suggested reviewers

brenelz
Sheraff

Poem

🐰 A lazy rabbit hops through dev mode's night,
When function IDs go missing—oh, what a sight!
Base64 decoding, modules compile with care,
Registry checked twice (because it's only fair!)
No more 500 errors, just smooth sailing through,
The Second Dev Start works perfectly true! 🎉

🚥 Pre-merge checks | ✅ 4 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Merge Conflict Detection	⚠️ Warning	❌ Merge conflicts detected (3 files): ⚔️ `packages/react-router/tests/router.test.tsx` (content) ⚔️ `packages/router-core/src/load-matches.ts` (content) ⚔️ `packages/start-plugin-core/src/start-compiler-plugin/plugin.ts` (content) These conflicts must be resolved before merging into `main`.	Resolve conflicts locally and push changes to this branch.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: implementing lazy compilation of server functions on dev restart to fix the invalid ID error, which directly addresses the root cause documented in issue `#6609`.
Linked Issues check	✅ Passed	The code changes implement lazy-validation and lazy-compilation of server function IDs in development mode, which directly addresses issue `#6609`'s requirement to eliminate the 'Invalid server function ID' error on dev server restart.
Out of Scope Changes check	✅ Passed	All changes are scoped to fixing the server function ID validation issue; no unrelated modifications to other features or systems are present in the changeset.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

📝 Generate docstrings

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch fix-6609

⚔️ Resolve merge conflicts (beta)

Auto-commit resolved conflicts to branch fix-6609
Create stacked PR with resolved conflicts
Post resolved changes as copyable diffs in a comment

No actionable comments were generated in the recent review. 🎉

🧹 Recent nitpick comments

packages/start-plugin-core/src/start-compiler-plugin/plugin.ts (2)
408-410: Consider logging errors for debugging.

The empty catch block will silently discard any decoding or fetching errors. While falling through to the error on line 413 is correct behavior, logging the caught exception would help developers troubleshoot why lazy compilation failed.
🛠️ Suggested improvement
-            } catch {
-              // Decoding or fetching failed — fall through to error
-            }
+            } catch (e) {
+              // Decoding or fetching failed — fall through to error
+              // Log for debugging purposes
+              console.debug('[tanstack-start] Lazy compilation failed for server fn:', fnId, e)
+            }
391-401: Optional: Validate resolved path stays within project root.

The decoded file path is resolved relative to root, but malformed IDs could theoretically resolve to paths outside the project. While this is dev-only and Vite's fetchModule likely rejects invalid paths, explicit validation would be more defensive.
🛡️ Optional defensive check
                 // Resolve to absolute path
                 const absPath = resolvePath(root, sourceFile)

+                // Ensure resolved path is within project root
+                if (!absPath.startsWith(root)) {
+                  throw new Error(`Server function source file escapes project root: ${sourceFile}`)
+                }
+
                 // Trigger transform of the source file in this environment,

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

nx-cloud · 2026-02-14T00:47:38Z

View your CI Pipeline Execution ↗ for commit 4a3ed02

Command	Status	Duration	Result
`nx affected --targets=test:eslint,test:unit,tes...`	✅ Succeeded	9m 11s	View ↗
`nx run-many --target=build --exclude=examples/*...`	✅ Succeeded	21s	View ↗

☁️ Nx Cloud last updated this comment at 2026-02-14 00:57:28 UTC

pkg-pr-new · 2026-02-14T00:49:42Z

More templates

@tanstack/arktype-adapter

npm i https://pkg.pr.new/TanStack/router/@tanstack/arktype-adapter@6655

@tanstack/eslint-plugin-router

npm i https://pkg.pr.new/TanStack/router/@tanstack/eslint-plugin-router@6655

@tanstack/history

npm i https://pkg.pr.new/TanStack/router/@tanstack/history@6655

@tanstack/nitro-v2-vite-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/nitro-v2-vite-plugin@6655

@tanstack/react-router

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router@6655

@tanstack/react-router-devtools

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router-devtools@6655

@tanstack/react-router-ssr-query

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router-ssr-query@6655

@tanstack/react-start

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start@6655

@tanstack/react-start-client

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start-client@6655

@tanstack/react-start-server

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start-server@6655

@tanstack/router-cli

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-cli@6655

@tanstack/router-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-core@6655

@tanstack/router-devtools

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-devtools@6655

@tanstack/router-devtools-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-devtools-core@6655

@tanstack/router-generator

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-generator@6655

@tanstack/router-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-plugin@6655

@tanstack/router-ssr-query-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-ssr-query-core@6655

@tanstack/router-utils

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-utils@6655

@tanstack/router-vite-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-vite-plugin@6655

@tanstack/solid-router

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-router@6655

@tanstack/solid-router-devtools

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-router-devtools@6655

@tanstack/solid-router-ssr-query

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-router-ssr-query@6655

@tanstack/solid-start

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start@6655

@tanstack/solid-start-client

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start-client@6655

@tanstack/solid-start-server

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start-server@6655

@tanstack/start-client-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-client-core@6655

@tanstack/start-fn-stubs

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-fn-stubs@6655

@tanstack/start-plugin-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-plugin-core@6655

@tanstack/start-server-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-server-core@6655

@tanstack/start-static-server-functions

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-static-server-functions@6655

@tanstack/start-storage-context

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-storage-context@6655

@tanstack/valibot-adapter

npm i https://pkg.pr.new/TanStack/router/@tanstack/valibot-adapter@6655

@tanstack/virtual-file-routes

npm i https://pkg.pr.new/TanStack/router/@tanstack/virtual-file-routes@6655

@tanstack/vue-router

npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-router@6655

@tanstack/vue-router-devtools

npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-router-devtools@6655

@tanstack/vue-router-ssr-query

npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-router-ssr-query@6655

@tanstack/vue-start

npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-start@6655

@tanstack/vue-start-client

npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-start-client@6655

@tanstack/vue-start-server

npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-start-server@6655

@tanstack/zod-adapter

npm i https://pkg.pr.new/TanStack/router/@tanstack/zod-adapter@6655

commit: 4a3ed02

fix: lazy-compile server fn on dev restart to avoid invalid ID error

4a3ed02

fixes #6609

github-actions bot added the package: start-plugin-core label Feb 14, 2026

schiller-manuel merged commit f212098 into main Feb 14, 2026
6 checks passed

schiller-manuel deleted the fix-6609 branch February 14, 2026 00:59

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix: lazy-compile server fn on dev restart to avoid invalid ID error#6655

fix: lazy-compile server fn on dev restart to avoid invalid ID error#6655
schiller-manuel merged 1 commit intomainfrom
fix-6609

schiller-manuel commented Feb 14, 2026 •

edited by coderabbitai bot

Loading

Uh oh!

coderabbitai bot commented Feb 14, 2026 •

edited

Loading

Walkthrough

Changes

Sequence Diagram

Estimated code review effort

Possibly related PRs

Suggested labels

Suggested reviewers

Poem

Uh oh!

nx-cloud bot commented Feb 14, 2026 •

edited

Loading

Uh oh!

pkg-pr-new bot commented Feb 14, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

schiller-manuel commented Feb 14, 2026 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Uh oh!

coderabbitai bot commented Feb 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram

Estimated code review effort

Possibly related PRs

Suggested labels

Suggested reviewers

Poem

Uh oh!

nx-cloud bot commented Feb 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pkg-pr-new bot commented Feb 14, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

schiller-manuel commented Feb 14, 2026 •

edited by coderabbitai bot

Loading

coderabbitai bot commented Feb 14, 2026 •

edited

Loading

nx-cloud bot commented Feb 14, 2026 •

edited

Loading