api: HEAD requests fail for derived JSON endpoints

Open Beginner friendly
  • Is something wrong?
#12,413 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
78/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
typescript
Domain
api, backend

Research direction

Start in packages/function/src/worker.ts: the catalogResponse function (around lines 209-224) and the schema route (around lines 67-73). Both call .json() on an asset or API response that is empty for HEAD requests. Reproduce with curl -I 'https://models.dev/model-schema.json' and the multi-type api.json?type=... query. Done means HEAD returns the same status and headers as GET without parsing a body, and the existing 15 worker tests still pass, plus new HEAD regression tests for the schema and multi-type routes.

Written by the indexing model from the issue text.

Description

HEAD returns 500 for /model-schema.json and multi-type catalog requests, while the corresponding GET requests return 200. Plain /api.json works with both methods.

Reproduced locally and on the public site; still present on current dev, 8b715df235126f6efcf4ab9b2e41c45f5ec74184.

Reproduction

curl -I 'https://models.dev/api.json'                     # 200, control
curl -I 'https://models.dev/api.json?type=chat,decision'  # 500
curl -I 'https://models.dev/model-schema.json'           # 500
curl -sS -o /dev/null -w '%{http_code}\n' \
  'https://models.dev/model-schema.json'                 # GET: 200

Cause

In catalogResponse, the asset request inherits HEAD. The asset correctly has no response body, but the multi-type path calls assetResponse.json(). The schema route similarly calls apiResponse.json(). Both throw SyntaxError: Unexpected end of JSON input.

Local regression tests reproduce this on all four multi-type catalog routes and on schema requests. GET/static-HEAD controls, invalid-type 400 and conditional HEAD/304 pass. A separate real loopback HTTP asset server reproduces the schema failure too. The failures repeated across ten runs; the existing 15 worker tests pass. Environment: macOS 15.6.1/arm64, Bun 1.4.4.

Expected: return the appropriate metadata without parsing a bodyless asset response or sending HEAD response content. See RFC 9110, 9.3.2.

I'd like to work on a fix limited to HEAD handling and regression tests, keeping GET output, type validation, ETags/304s and CORS unchanged. Would that scope fit?

Dominant language
TypeScript
Stars
7.5k
Forks
2k
Avg merge
39m
Merged PRs (30d)
904

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from anomalyco/models.dev

All issues in anomalyco/models.dev

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.