fix: Vercel 404 on /api/v1/meta and /api/v1/packages — path normalisation, kernel boot resilience, broker-optional metadata by Copilot · Pull Request #933 · objectstack-ai/objectstack

Copilot · 2026-03-18T14:53:45Z

Studio's Vercel deployment returns 404 for /api/v1/meta and /api/v1/packages. Three independent root causes: no error handling in the serverless catch-all (boot failures silently swallowed), no path normalisation (some runtimes strip /api/ prefix), and handleMetadata() unconditionally calling ensureBroker() which throws 500 in lightweight setups.

`apps/studio/api/[...path].ts` — catch-all handler

Wrap getApp() + inner.fetch() in try-catch; boot failures return structured 500 JSON instead of being swallowed
Normalise request path: prepend /api if the runtime stripped the function directory prefix

`apps/studio/api/_kernel.ts` — kernel cold-start

Shared boot promise prevents concurrent cold-start requests from racing duplicate initialisations
Validate broker shim after kernel.bootstrap() — reattach if lost
Seed-data failures are non-fatal (logged, not thrown)

`packages/runtime/src/http-dispatcher.ts` — broker-optional metadata

handleMetadata() uses this.kernel.broker ?? null instead of this.ensureBroker()
All broker.call() sites guarded with if (broker) — falls back to protocol service → ObjectQL registry → hardcoded defaults
Direct registry path for object lookups when broker is unavailable:

// Before: always throws if broker is nullconstbroker=this.ensureBroker();// After: graceful degradationconstbroker=this.kernel.broker??null;// ...if(broker){constdata=awaitbroker.call('metadata.objects',{ packageId }, ...);return{handled: true,response: this.success(data)};}// Fallback: use ObjectQL registry directlyconstqlService=awaitthis.getObjectQLService();if(qlService?.registry){constobjs=qlService.registry.getAllObjects(packageId);return{handled: true,response: this.success({type: 'object',items: objs})};}

Tests

5 new Hono tests: Vercel outer→inner delegation for meta, packages, discovery, path normalisation, error propagation
7 new runtime tests: broker-less metadata degradation across all path shapes (root types, object list, single object, published, save)

Original prompt

This section details on the original issue you should resolve
<issue_title>Vercel 部署依然404：/api/v1/meta 和 /api/v1/packages 路由未生效且 broker 未挂载</issue_title>
<issue_description>## 复现问题描述
在 Vercel 上部署 ObjectStack Studio 后，/api/v1/meta 和 /api/v1/packages 路由依然返回 404，控制台持续报错，前端核心元数据与包列表接口不可用。
客观现象
访问 https://play.objectstack.ai/api/v1/meta 与 /api/v1/packages 返回 404
控制台日志 [Console] Starting in Server mode，尝试 fetch /api/v1/packages 与 /api/v1/meta
HTTP response 多次 404 (Not Found)
页面无法加载核心功能
深度分析
Hono 路由 catch-all 实际是注册了，但 Vercel path prefix 很可能导致路径未命中
Vercel 的 /api/[...path].ts 路由和内部 createHonoApp 的 prefix /api/v1 可能双重叠加，或者存在被截断。
若请求传递路径为 /v1/meta，但 Hono 注册路径为 /api/v1/meta，则完全无法匹配，直接 404。
dispatcher.dispatch() 已覆盖 meta/packages 路由，问题多半在于 serverless 环境路径偏移。
broker shim 挂载虽有实现，但 cold start 时 kernel/app 启动失败未捕获，可能直接甩 500，或者 broker 为 null 抛异常。
handleMetadata/handlePackages 方法直接 ensureBroker()，一旦 broker 未挂载或初始化失败，会抛 500。
结论
当前 issue [Bug] Vercel部署后 /api/v1/meta 和 /api/v1/packages 路由404，导致前端无法加载元数据和包列表 #930 实际未完全解决，404 问题依然存在。
路由 catch-all 机制逻辑没问题，问题多半在于 Vercel/FaaS 路径以及应用冷启动与 broker lifecycle 的配合。
服务端代码需针对 Vercel 路径前缀、Hono 多级 path、以及 kernel/broker 的 robust 初始化机制做架构级修正。
推荐修复与长期方案
在 serverless handler 层打印路径/日志，定位请求 path 是否被修正或被截断。
梳理 prefix 和 handler注册，防止内部 Hono prefix 与 Vercel catch-all 产生双重前缀或错配。
kernel/app 的初始化需要更健壮，所有异常都应有日志、并降级到健康提示，不应静默挂死。
broker shim 强制挂载与 broker 相关依赖初始化需全程校验，并应支持无 broker 降级兼容。
补充 Vercel/serverless 路由端到端 e2e 测试用例。
相关分析已在 #930 提供，可附引用。
cc @hotlong </issue_description>
Comments on the Issue (you are @copilot in this section)

FixesVercel 部署依然404：/api/v1/meta 和 /api/v1/packages 路由未生效且 broker 未挂载 #932

📱 Kick off Copilot coding agent tasks wherever you are with GitHub Mobile, available on iOS and Android.

vercel · 2026-03-18T14:53:59Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
objectstack-play	Ready	Preview, Comment	Mar 18, 2026 3:17pm
spec	Ready	Preview, Comment	Mar 18, 2026 3:17pm

…lient metadata - api/[...path].ts: Add try-catch + path normalisation for /api prefix - api/_kernel.ts: Boot promise lock, broker reattach, non-fatal seed errors - http-dispatcher.ts: handleMetadata() no longer requires broker upfront - Add 12 new tests for Vercel delegation and broker-less metadata handling - Update CHANGELOG.md Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Copilot

Pull request overview

Fixes Studio’s Vercel serverless routing failures for /api/v1/meta and /api/v1/packages by hardening the serverless catch-all, making kernel boot more resilient under cold-start concurrency, and allowing metadata handling to degrade gracefully when a broker is unavailable.

Changes:

Add request path normalization + structured error handling in the Vercel catch-all handler.
Add a shared boot promise and non-fatal seeding behavior to prevent cold-start races and improve resiliency.
Make HttpDispatcher.handleMetadata() broker-optional with ObjectQL registry fallbacks; add tests for broker-less behavior and delegation behavior in the Hono adapter.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
apps/studio/api/[...path].ts	Wraps serverless delegation in try/catch and normalizes paths to preserve `/api` prefix before forwarding to the inner Hono app.
apps/studio/api/_kernel.ts	Adds cold-start initialization lock via shared promise; validates broker shim; makes seeding non-fatal.
packages/runtime/src/http-dispatcher.ts	Updates metadata handler to avoid requiring a broker and to fall back to protocol/ObjectQL registry where possible.
packages/runtime/src/http-dispatcher.test.ts	Adds tests validating metadata degradation behavior when the kernel has no broker.
packages/adapters/hono/src/hono.test.ts	Adds tests for outer→inner Hono delegation and intended path normalization/error propagation scenarios.
CHANGELOG.md	Documents the Vercel routing fix, kernel boot resiliency, and broker-optional metadata behavior.

+ }
+ // Try listing items of the given type
+ const items = qlService.registry.listItems?.(typeOrName, packageId);
+ if (items && items.length > 0) {


+ it('handles path normalisation (strips prefix correctly) through delegation', async () => {
+ const innerApp = createHonoApp({ kernel: mockKernel, prefix: '/api/v1' });
+
+ const outerApp = new Hono();
+ outerApp.all('/*', async (c) => {
+ // Simulate the normalisation logic from [...path].ts
+ const url = new URL(c.req.url);
+ if (!url.pathname.startsWith('/api')) {
+ url.pathname = '/api' + url.pathname;
+ const request = new Request(url.toString(), c.req.raw);


Initial plan
ca310a1

CopilotAI assigned Copilot and hotlong Mar 18, 2026

Copilotstarted work on behalf of hotlong March 18, 2026 14:53 View session

vercelBotdeployed to Preview – spec March 18, 2026 14:56 View deployment

vercelBotdeployed to Preview – objectstack-play March 18, 2026 14:57 View deployment

CopilotAIand others added 2 commits March 18, 2026 15:08

fix: address code review — null check for getObject, boot error logging
ee369af
Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

CopilotAI changed the title ~~[WIP] Fix 404 errors for /api/v1/meta and /api/v1/packages routes~~fix: Vercel 404 on /api/v1/meta and /api/v1/packages — path normalisation, kernel boot resilience, broker-optional metadataMar 18, 2026

CopilotAI requested a review from hotlong March 18, 2026 15:12

Copilotfinished work on behalf of hotlong March 18, 2026 15:12

vercelBotdeployed to Preview – objectstack-play March 18, 2026 15:14 View deployment

vercelBotdeployed to Preview – spec March 18, 2026 15:17 View deployment

hotlong marked this pull request as ready for review March 19, 2026 02:13

CopilotAI review requested due to automatic review settings March 19, 2026 02:13

hotlong merged commit d0c58d6 into mainMar 19, 2026
5 checks passed

CopilotAI reviewed Mar 19, 2026
View reviewed changes

hotlong mentioned this pull request Mar 19, 2026
[Refactor] Migrate API layer to Hono + Vercel Edge/Node adapter for long-term monorepo stability #934
Closed
8 tasks

CopilotAI mentioned this pull request Mar 19, 2026
Migrate API layer from catch-all handler to Hono + Vercel adapter #935
Merged

Navigation Menu

Uh oh!

fix: Vercel 404 on /api/v1/meta and /api/v1/packages — path normalisation, kernel boot resilience, broker-optional metadata - #933

fix: Vercel 404 on /api/v1/meta and /api/v1/packages — path normalisation, kernel boot resilience, broker-optional metadata#933
hotlong merged 3 commits into
mainfrom
copilot/fix-vercel-deployment-404-errors

CopilotAI commented Mar 18, 2026•
edited
Loading

Uh oh!

vercelBot commented Mar 18, 2026•
edited
Loading

Uh oh!

Uh oh!

CopilotAI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

CopilotAI commented Mar 18, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

apps/studio/api/[...path].ts — catch-all handler

apps/studio/api/_kernel.ts — kernel cold-start

packages/runtime/src/http-dispatcher.ts — broker-optional metadata

Tests

客观现象

深度分析

结论

推荐修复与长期方案

Comments on the Issue (you are @copilot in this section)

Uh oh!

vercelBot commented Mar 18, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

CopilotAI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

CopilotAI commented Mar 18, 2026•
edited
Loading

`apps/studio/api/[...path].ts` — catch-all handler

`apps/studio/api/_kernel.ts` — kernel cold-start

`packages/runtime/src/http-dispatcher.ts` — broker-optional metadata

vercelBot commented Mar 18, 2026•
edited
Loading