overleaf/overleaf · error

unprocessable entity

Error message

unprocessable entity

What it means

HttpErrorHandler.unprocessableEntity sends HTTP 422 with message defaulting to 'unprocessable entity'. HTML clients get the general/400 'Client Error' page with the message; JSON clients get message and info via renderJSONError. It signals the request is syntactically valid but semantically cannot be processed.

Source

Thrown at services/web/app/src/Features/Errors/HttpErrorHandler.mjs:121

      default:
        return plainTextResponse(res, 'restricted')
    }
  },

  notFound(req, res, message = 'not found', info = {}) {
    res.status(404)
    switch (req.accepts(['html', 'json'])) {
      case 'html':
        return res.render('general/404', { title: 'page_not_found' })
      case 'json':
        return renderJSONError(res, message, info)
      default:
        return plainTextResponse(res, 'not found')
    }
  },

  unprocessableEntity(req, res, message = 'unprocessable entity', info = {}) {
    res.status(422)
    switch (req.accepts(['html', 'json'])) {
      case 'html':
        return res.render('general/400', {
          title: 'Client Error',
          message,
        })
      case 'json':
        return renderJSONError(res, message, info)
      default:
        return plainTextResponse(res, 'unprocessable entity')
    }
  },

  legacyInternal(req, res, message, err) {
    req.logger.addFields({ err })
    req.logger.setLevel('error')
    handleGeneric500Error(req, res, 500, message)
  },

View on GitHub (pinned to 28ad3b03b7)

Solutions

1. Read the message/info to identify which semantic rule failed and correct the payload
2. Run the same domain validations client-side before submitting
3. Check API changelog for validation rules that changed between versions

Example fix

// before
await updateDoc(docId, { version: -1 }) // 422
// after
if (version > 0) await updateDoc(docId, { version })

function isValidPayload(p) {
  return p && typeof p.version === 'number' && p.version > 0 &&
    typeof p.name === 'string' && p.name.length > 0
}
if (!isValidPayload(payload)) {
  // fix payload before submitting
}

try {
  await submit(payload)
} catch (err) {
  if (err.status === 422) {
    // inspect err.body.message/info for the failing semantic rule
  }
}

When it happens

Trigger: Calling HttpErrorHandler.unprocessableEntity(req, res, message, info) when a request passes parsing/validation but fails business rules, e.g. malformed entity references or state-machine violations.

Common situations: Well-formed JSON whose field values are logically invalid (bad enums, impossible dates), payloads that skip required domain checks, or API clients not updated for changed validation rules.

Related errors

• File too large
• cipherLabel cannot be empty
• cipherLabel must not contain a colon (:), got ${cipherLabel}
• cipherLabel must contain version suffix (e.g. 2042.1-v42), g
• cipherPasswords['${cipherLabel}'] is too short

AI-assisted analysis of overleaf/overleaf@28ad3b03b7 (2026-09-03). Data as JSON: /api/errors/c0288906ab0fcdef. Report an issue: GitHub.